如何快速玩轉swagger

Spring Boot 框架是目前非常流行的微服務框架，我們很多情況下使用它來提供 Rest API。而對於 Rest API 來說很重要的一部分內容就是文檔，Swagger 爲我們提供了一套通過代碼和註解自動生成文檔的方法，這一點對於保證 API 文檔的及時性將有很大的幫助。本文將使用 Swagger 2 規範的 Springfox 實現來了展示如何在 Spring Boot 項目中使用 Swagger，主要包含了如何使用 Swagger 自動生成文檔、使用 Swagger 文檔以及 Swagger 相關的一些高級配置和註解。

Swagger 簡介

Swagger 是一套基於 OpenAPI 規範構建的開源工具，可以幫助我們設計、構建、記錄以及使用 Rest API。Swagger 主要包含了以下三個部分：

•Swagger Editor ：基於瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規範。•Swagger UI：它會將我們編寫的 OpenAPI 規範呈現爲交互式的 API 文檔，後文我將使用瀏覽器來查看並且操作我們的 Rest API。•Swagger Codegen：它可以通過爲 OpenAPI（以前稱爲 Swagger）規範定義的任何 API 生成服務器存根和客戶端 SDK 來簡化構建過程。

爲什麼要使用 Swagger

當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文檔將會極大的提高我們的工作效率。傳統意義上的文檔都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文檔的及時性，這種文檔久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文檔的方式，下面我們就來了解一下它的優點：

•代碼變，文檔變。只需要少量的註解，Swagger 就可以根據代碼自動生成 API 文檔，很好的保證了文檔的時效性。 跨語言性，支持 40 多種語言。•Swagger UI 呈現出來的是一份可交互式的 API 文檔，我們可以直接在文檔頁面嘗試 API 的調用，省去了準備複雜的調用參數的過程。•還可以將文檔規範導入相關的工具（例如 SoapUI）, 這些工具將會爲我們自動地創建自動化測試。

以上這些優點足以說明我們爲什麼要使用 Swagger 了，您是否已經對 Swagger 產生了濃厚的興趣了呢？下面我們就將一步一步地在 Spring Boot 項目中集成和使用 Swagger，讓我們從準備一個 Spring Boot 的 Web 項目開始吧。

準備 Spring Boot Web 項目

在這一步我們將準備一個基礎的 Spring Boot 的 Web 項目，並且提供後面所需要的所有 API。

創建一個空的 Spring Boot 項目

您可以通過 Spring Initializr 頁面 生成一個空的 Spring Boot 項目，當然也可以下載 springboot-pom.xml 文件，然後使用 Maven 構建一個 Spring Boot 項目。項目創建完成後，爲了方便後面代碼的編寫您可以將其導入到您喜歡的 IDE 中，我這裏選擇了 Intelli IDEA 打開。

添加依賴

由於創建的是一個 Web 項目，所以我們需要依賴 Spring Boot 的 Web 組件，只需要在 pom.xml 增加如下內容即可：

清單 1. 添加 Web 依賴

<dependency>    <groupId>org.springframework.boot</groupId>    <artifactId>spring-boot-starter-web</artifactId></dependency>

編寫接口

•首先我們創建三個包：cn.smalltech.swagger.controller、cn.smalltech.swagger.testcontroller 以及 cn.smalltech.swagger.model。•在 controller 包下新建 UserController.java 類，在 testcontroller 包下新建 TestController.java 類，在 model 包下新建 User.java 類。•UserController 提供用戶的增、刪、改、查四個接口，TestContrller 提供一個測試接口，這裏粘上 UserController.java 的代碼，其餘代碼可以查看源碼 。

清單 2. UserController.java 代碼

@RestController@RequestMapping("/user")public class UserController {    @PostMapping("/add")    public boolean addUser(@RequestBody User user) {        return false;    }    @GetMapping("/find/{id}")    public User findById(@PathVariable("id") int id) {        return new User();    }    @PutMapping("/update")    public boolean update(@RequestBody User user) {        return true;    }    @DeleteMapping("/delete/{id}")    public boolean delete(@PathVariable("id") int id) {        return true;    }}

集成 Swagger2

經過上面的步驟，我們已經擁有了五個接口，分別是:

•/user/add：新增用戶。•/user/find/{id}：根據 id 查詢用戶。•/user/update：更新用戶。•/user/delete/{id}：根據 id 刪除用戶。•/test/test：測試接口。 下面我們將通過集成 Swagger2，然後爲這 5 個 Rest API 自動生成接口文檔。

添加依賴

首先要做的自然是添加 Swagger2 所需要的依賴包：

清單 3. 添加 Swagger 依賴

<dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.9.2</version></dependency>

Java 配置

Springfox 提供了一個 Docket 對象，讓我們可以靈活的配置 Swagger 的各項屬性。下面我們新建一個 cn.itweknow.sbswagger.conf.SwaggerConfig.java 類，並增加如下內容:

清單 4. Swagger Java 配置

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket api() {        return new Docket(DocumentationType.SWAGGER_2)                .select()                .apis(RequestHandlerSelectors.any())                .paths(PathSelectors.any())                .build();    }}

注意: @Configuration 是告訴 Spring Boot 需要加載這個配置類， @EnableSwagger2 是啓用 Swagger2，如果沒加的話自然而然也就看不到後面的驗證效果了。

驗證 至此，我們已經成功的在 Spring Boot 項目中集成了 Swagger2，啓動項目後，我們可以通過在瀏覽器中訪問 http://localhost:8080/v2/api-docs 來驗證，您會發現返回的結果是一段 JSON 串，可讀性非常差。幸運的是 Swagger2 爲我們提供了可視化的交互界面 SwaggerUI，下面我們就一起來試試吧。

集成 Swagger UI 添加依賴 和之前一樣，集成的第一步就是添加相關依賴，在 pom.xml 中添加如下內容即可：

清單 5. 添加 Swagger UI 依賴

io.springfox   springfox-swagger-ui   2.9.2

訪問驗證

其實就只需要添加一下依賴就可以了，我們重新啓動一下項目，然後在瀏覽器中訪問 http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:

圖 1. Swagger UI

可以看到雖然可讀性好了一些，但對接口的表述還不是那麼的清楚，接下來我們就通過一些高級配置，讓這份文檔變的更加的易讀。

高級配置

文檔相關描述配置

•1.通過在控制器類上增加 @Api 註解，可以給控制器增加描述和標籤信息。

清單 6. 給 Controller 添加描述信息

@Api(tags = "用戶相關接口", description = "提供用戶相關的 Rest API")public class UserController

•2.通過在接口方法上增加 @ApiOperation 註解來展開對接口的描述，當然這個註解還可以指定很多內容，我們在下面的相關注解說明章節中詳細解釋。

清單 7. 給接口添加描述信息

@ApiOperation("新增用戶接口")@PostMapping("/add")public boolean addUser(@RequestBody User user) {    return false;}

•3.實體描述，我們可以通過 @ApiModel 和 @ApiModelProperty 註解來對我們 API 中所涉及到的對象做描述。

清單 8. 給實體類添加描述信息

@ApiModel("用戶實體")public class User {    @ApiModelProperty("用戶 id")private int id;}

•4.文檔信息配置，Swagger 還支持設置一些文檔的版本號、聯繫人郵箱、網站、版權、開源協議等等信息，但與上面幾條不同的是這些信息不是通過註解配置，而是通過創建一個 ApiInfo 對象，並且使用 Docket.appInfo() 方法來設置，我們在 SwaggerConfig.java 類中新增如下內容即可。

清單 9. 配置文檔信息

@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select()            .apis(RequestHandlerSelectors.any())            .paths(PathSelectors.any())            .build()            .apiInfo(apiInfo());}private ApiInfo apiInfo() {return new ApiInfo(            "Spring Boot 項目集成 Swagger 實例文檔",            "我的博客網站：https://smalltechnologyjun.com，歡迎大家訪問。",            "API V1.0",            "Terms of service",            new Contact("名字想好沒", "https://smalltechnologyjun.com", "[email protected]"),                "Apache", "http://www.apache.org/", Collections.emptyList());}

經過上面的步驟，我們的文檔將會變成下圖的樣子，現在看起來就清楚很多了。

圖 2. 補全信息後的 Swagger 文檔界面

接口過濾

有些時候我們並不是希望所有的 Rest API 都呈現在文檔上，這種情況下 Swagger2 提供給我們了兩種方式配置，一種是基於 @ApiIgnore 註解，另一種是在 Docket 上增加篩選。

1.@ApiIgnore 註解。

如果想在文檔中屏蔽掉刪除用戶的接口（user/delete），那麼只需要在刪除用戶的方法上加上 @ApiIgnore 即可。

清單 10. @ApiIgnore 使用實例

@ApiIgnorepublic boolean delete(@PathVariable("id") int id)

1.在 Docket 上增加篩選。Docket 類提供了 apis() 和 paths() 兩個方法來幫助我們在不同級別上過濾接口：•apis() ：這種方式我們可以通過指定包名的方式，讓 Swagger 只去某些包下面掃描。•paths() ：這種方式可以通過篩選 API 的 url 來進行過濾。 在集成 Swagger2 的章節中我們這兩個方法指定的都是掃描所有，沒有指定任何過濾條件。如果我們在我們修改之前定義的 Docket 對象的 apis() 方法和 paths() 方法爲下面的內容，那麼接口文檔將只會展示 /user/add 和 /user/find/{id} 兩個接口。

清單 11. 使用 Docket 配置接口篩選

.apis(RequestHandlerSelectors.basePackage("cn.itweknow.sbswagger.controller")).paths(Predicates.or(PathSelectors.ant("/user/add"),        PathSelectors.ant("/user/find/*")))

圖 3. 經過篩選過後的 Swagger 文檔界面

自定義響應消息

Swagger 允許我們通過 Docket 的 globalResponseMessage() 方法全局覆蓋 HTTP 方法的響應消息，但是首先我們得通過 Docket 的 useDefaultResponseMessages 方法告訴 Swagger 不使用默認的 HTTP 響應消息，假設我們現在需要覆蓋所有 GET 方法的 500 和 403 錯誤的響應消息，我們只需要在 SwaggerConfig.java 類中的 Docket Bean 下添加如下內容：

清單 12. 自定義響應消息

.useDefaultResponseMessages(false).globalResponseMessage(RequestMethod.GET, newArrayList(new ResponseMessageBuilder()              .code(500)              .message("服務器發生異常")              .responseModel(new ModelRef("Error"))              .build(),       new ResponseMessageBuilder()              .code(403)              .message("資源不可用")              .build()));

添加如上面的代碼後，如下圖所示，您會發現在 SwaggerUI 頁面展示的所有 GET 類型請求的 403 以及 500 錯誤的響應消息都變成了我們自定義的內容。

圖 4. 自定義響應消息

Swagger UI 的使用

接口查看

SwaggerUI 會以列表的方式展示所有掃描到的接口，初始狀態是收縮的，我們只需要點擊展開就好，而且會在左邊標識接口的請求方式（GET、POST、PUT、DELETE 等等）。

圖 5. Swagger 接口列表界面

接口調用

如下圖所示，點擊接口展開後頁面右上角的 Try it out 按鈕後，頁面會變成如圖所示：

圖 6. 接口詳情界面

SwaggerUI 會給我們自動填充請求參數的數據結構，我們需要做的只是點擊 Execute 即可發起調用

圖 7. 接口調用界面

Model

如下圖所示，SwaggerUI 會通過我們在實體上使用的 @ApiModel 註解以及 @ApiModelProperty 註解來自動補充實體以及其屬性的描述和備註。

圖 8. 實體界面

相關注解說明

在本文中我將給出一些 Swagger 中常用的註解以及其常用的屬性，並對其一一解釋，方便您查看。

Controller 相關注解

@Api: 可設置對控制器的描述。

表 1. @Api 主要屬性

註解屬性	類型	描述
tags	String[]	控制器標籤。
description	String	控制器描述（該字段被申明爲過期）

表 2. @ApiOperation 主要屬性

註解屬性	類型	描述
value	String	接口說明
notes	String	接口發佈說明。
tags	Stirng[]	標籤。
response	Class<?>	接口返回類型。
httpMethod	String	接口請求方式。

@ApiIgnore: Swagger 文檔不會顯示擁有該註解的接口。 @ApiImplicitParams: 用於描述接口的非對象參數集。 @ApiImplicitParam: 用於描述接口的非對象參數，一般與 @ApiImplicitParams 組合使用。

持續精彩請點擊小程序

本文分享自微信公衆號 - 小技術君（gh_2fd927ba125d）。
如有侵權，請聯繫 [email protected] 刪除。
本文參與“OSC源創計劃”，歡迎正在閱讀的你也加入，一起分享。