Spring Boot 框架是目前非常流行的微服務(wù)框架，我們很多情況下使用它來(lái)提供 Rest API。而對(duì)于 Rest API 來(lái)說(shuō)很重要的一部分內(nèi)容就是文檔，Swagger 為我們提供了一套通過(guò)代碼和注解自動(dòng)生成文檔的方法，這一點(diǎn)對(duì)于保證 API 文檔的及時(shí)性將有很大的幫助。本文將使用 Swagger 2 規(guī)范的 Springfox 實(shí)現(xiàn)來(lái)了展示如何在 Spring Boot 項(xiàng)目中使用 Swagger，主要包含了如何使用 Swagger 自動(dòng)生成文檔、使用 Swagger 文檔以及 Swagger 相關(guān)的一些高級(jí)配置和注解。

Swagger 簡(jiǎn)介

Swagger 是一套基于 OpenAPI 規(guī)范構(gòu)建的開(kāi)源工具，可以幫助我們?cè)O(shè)計(jì)、構(gòu)建、記錄以及使用 Rest API。Swagger 主要包含了以下三個(gè)部分：

?Swagger Editor ：基于瀏覽器的編輯器，我們可以使用它編寫(xiě)我們 OpenAPI 規(guī)范。?Swagger UI：它會(huì)將我們編寫(xiě)的 OpenAPI 規(guī)范呈現(xiàn)為交互式的 API 文檔，后文我將使用瀏覽器來(lái)查看并且操作我們的 Rest API。?Swagger Codegen：它可以通過(guò)為 OpenAPI(以前稱為 Swagger)規(guī)范定義的任何 API 生成服務(wù)器存根和客戶端 SDK 來(lái)簡(jiǎn)化構(gòu)建過(guò)程。

為什么要使用 Swagger

當(dāng)下很多公司都采取前后端分離的開(kāi)發(fā)模式，前端和后端的工作由不同的工程師完成。在這種開(kāi)發(fā)模式下，維持一份及時(shí)更新且完整的 Rest API 文檔將會(huì)極大的提高我們的工作效率。傳統(tǒng)意義上的文檔都是后端開(kāi)發(fā)人員手動(dòng)編寫(xiě)的，相信大家也都知道這種方式很難保證文檔的及時(shí)性，這種文檔久而久之也就會(huì)失去其參考意義，反而還會(huì)加大我們的溝通成本。而 Swagger 給我們提供了一個(gè)全新的維護(hù) API 文檔的方式，下面我們就來(lái)了解一下它的優(yōu)點(diǎn)：

?代碼變，文檔變。只需要少量的注解，Swagger 就可以根據(jù)代碼自動(dòng)生成 API 文檔，很好的保證了文檔的時(shí)效性。 跨語(yǔ)言性，支持 40 多種語(yǔ)言。?Swagger UI 呈現(xiàn)出來(lái)的是一份可交互式的 API 文檔，我們可以直接在文檔頁(yè)面嘗試 API 的調(diào)用，省去了準(zhǔn)備復(fù)雜的調(diào)用參數(shù)的過(guò)程。?還可以將文檔規(guī)范導(dǎo)入相關(guān)的工具(例如 SoapUI), 這些工具將會(huì)為我們自動(dòng)地創(chuàng)建自動(dòng)化測(cè)試。

以上這些優(yōu)點(diǎn)足以說(shuō)明我們?yōu)槭裁匆褂?Swagger 了，您是否已經(jīng)對(duì) Swagger 產(chǎn)生了濃厚的興趣了呢？下面我們就將一步一步地在 Spring Boot 項(xiàng)目中集成和使用 Swagger，讓我們從準(zhǔn)備一個(gè) Spring Boot 的 Web 項(xiàng)目開(kāi)始吧。

準(zhǔn)備 Spring Boot Web 項(xiàng)目

在這一步我們將準(zhǔn)備一個(gè)基礎(chǔ)的 Spring Boot 的 Web 項(xiàng)目，并且提供后面所需要的所有 API。

創(chuàng)建一個(gè)空的 Spring Boot 項(xiàng)目

您可以通過(guò) Spring Initializr 頁(yè)面 生成一個(gè)空的 Spring Boot 項(xiàng)目，當(dāng)然也可以下載 springboot-pom.xml 文件，然后使用 Maven 構(gòu)建一個(gè) Spring Boot 項(xiàng)目。項(xiàng)目創(chuàng)建完成后，為了方便后面代碼的編寫(xiě)您可以將其導(dǎo)入到您喜歡的 IDE 中，我這里選擇了 Intelli IDEA 打開(kāi)。

添加依賴

由于創(chuàng)建的是一個(gè) Web 項(xiàng)目，所以我們需要依賴 Spring Boot 的 Web 組件，只需要在 pom.xml 增加如下內(nèi)容即可：

清單 1. 添加 Web 依賴

org.springframework.boot spring-boot-starter-web

編寫(xiě)接口

?首先我們創(chuàng)建三個(gè)包：cn.smalltech.swagger.controller、cn.smalltech.swagger.testcontroller 以及 cn.smalltech.swagger.model。?在 controller 包下新建 UserController.java 類，在 testcontroller 包下新建 TestController.java 類，在 model 包下新建 User.java 類。?UserController 提供用戶的增、刪、改、查四個(gè)接口，TestContrller 提供一個(gè)測(cè)試接口，這里粘上 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

經(jīng)過(guò)上面的步驟，我們已經(jīng)擁有了五個(gè)接口，分別是:

?/user/add：新增用戶。?/user/find/{id}：根據(jù) id 查詢用戶。?/user/update：更新用戶。?/user/delete/{id}：根據(jù) id 刪除用戶。?/test/test：測(cè)試接口。 下面我們將通過(guò)集成 Swagger2，然后為這 5 個(gè) Rest API 自動(dòng)生成接口文檔。

添加依賴

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

清單 3. 添加 Swagger 依賴

io.springfox springfox-swagger2 2.9.2

Java 配置

Springfox 提供了一個(gè) Docket 對(duì)象，讓我們可以靈活的配置 Swagger 的各項(xiàng)屬性。下面我們新建一個(gè) cn.itweknow.sbswagger.conf.SwaggerConfig.java 類，并增加如下內(nèi)容:

清單 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 需要加載這個(gè)配置類， @EnableSwagger2 是啟用 Swagger2，如果沒(méi)加的話自然而然也就看不到后面的驗(yàn)證效果了。

驗(yàn)證 至此，我們已經(jīng)成功的在 Spring Boot 項(xiàng)目中集成了 Swagger2，啟動(dòng)項(xiàng)目后，我們可以通過(guò)在瀏覽器中訪問(wèn) http://localhost:8080/v2/api-docs 來(lái)驗(yàn)證，您會(huì)發(fā)現(xiàn)返回的結(jié)果是一段 JSON 串，可讀性非常差。幸運(yùn)的是 Swagger2 為我們提供了可視化的交互界面 SwaggerUI，下面我們就一起來(lái)試試吧。

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

清單 5. 添加 Swagger UI 依賴

io.springfox?springfox-swagger-ui?2.9.2

訪問(wèn)驗(yàn)證

其實(shí)就只需要添加一下依賴就可以了，我們重新啟動(dòng)一下項(xiàng)目，然后在瀏覽器中訪問(wèn) http://localhost:8080/swagger-ui.html 就可以看到如下的效果了:

圖 1. Swagger UI

可以看到雖然可讀性好了一些，但對(duì)接口的表述還不是那么的清楚，接下來(lái)我們就通過(guò)一些高級(jí)配置，讓這份文檔變的更加的易讀。

高級(jí)配置

文檔相關(guān)描述配置

?1.通過(guò)在控制器類上增加 @Api 注解，可以給控制器增加描述和標(biāo)簽信息。

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

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

?2.通過(guò)在接口方法上增加 @ApiOperation 注解來(lái)展開(kāi)對(duì)接口的描述，當(dāng)然這個(gè)注解還可以指定很多內(nèi)容，我們?cè)谙旅娴南嚓P(guān)注解說(shuō)明章節(jié)中詳細(xì)解釋。

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

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

?3.實(shí)體描述，我們可以通過(guò) @ApiModel 和 @ApiModelProperty 注解來(lái)對(duì)我們 API 中所涉及到的對(duì)象做描述。

清單 8. 給實(shí)體類添加描述信息

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

?4.文檔信息配置，Swagger 還支持設(shè)置一些文檔的版本號(hào)、聯(lián)系人郵箱、網(wǎng)站、版權(quán)、開(kāi)源協(xié)議等等信息，但與上面幾條不同的是這些信息不是通過(guò)注解配置，而是通過(guò)創(chuàng)建一個(gè) ApiInfo 對(duì)象，并且使用 Docket.appInfo() 方法來(lái)設(shè)置，我們?cè)?SwaggerConfig.java 類中新增如下內(nèi)容即可。

清單 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 項(xiàng)目集成 Swagger 實(shí)例文檔", "我的博客網(wǎng)站：https://smalltechnologyjun.com，歡迎大家訪問(wèn)。", "API V1.0", "Terms of service", new Contact("名字想好沒(méi)", "https://smalltechnologyjun.com", "xxxxx@gmail.com"), "Apache", "http://www.apache.org/", Collections.emptyList());}

經(jīng)過(guò)上面的步驟，我們的文檔將會(huì)變成下圖的樣子，現(xiàn)在看起來(lái)就清楚很多了。

圖 2. 補(bǔ)全信息后的 Swagger 文檔界面

接口過(guò)濾

有些時(shí)候我們并不是希望所有的 Rest API 都呈現(xiàn)在文檔上，這種情況下 Swagger2 提供給我們了兩種方式配置，一種是基于 @ApiIgnore 注解，另一種是在 Docket 上增加篩選。

1.@ApiIgnore 注解。

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

清單 10. @ApiIgnore 使用實(shí)例

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

1.在 Docket 上增加篩選。Docket 類提供了 apis() 和 paths() 兩個(gè)方法來(lái)幫助我們?cè)诓煌?jí)別上過(guò)濾接口：?apis() ：這種方式我們可以通過(guò)指定包名的方式，讓 Swagger 只去某些包下面掃描。?paths() ：這種方式可以通過(guò)篩選 API 的 url 來(lái)進(jìn)行過(guò)濾。 在集成 Swagger2 的章節(jié)中我們這兩個(gè)方法指定的都是掃描所有，沒(méi)有指定任何過(guò)濾條件。如果我們?cè)谖覀冃薷闹岸x的 Docket 對(duì)象的 apis() 方法和 paths() 方法為下面的內(nèi)容，那么接口文檔將只會(huì)展示 /user/add 和 /user/find/{id} 兩個(gè)接口。

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

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

圖 3. 經(jīng)過(guò)篩選過(guò)后的 Swagger 文檔界面

自定義響應(yīng)消息

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

清單 12. 自定義響應(yīng)消息

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

添加如上面的代碼后，如下圖所示，您會(huì)發(fā)現(xiàn)在 SwaggerUI 頁(yè)面展示的所有 GET 類型請(qǐng)求的 403 以及 500 錯(cuò)誤的響應(yīng)消息都變成了我們自定義的內(nèi)容。

圖 4. 自定義響應(yīng)消息

Swagger UI 的使用

接口查看

SwaggerUI 會(huì)以列表的方式展示所有掃描到的接口，初始狀態(tài)是收縮的，我們只需要點(diǎn)擊展開(kāi)就好，而且會(huì)在左邊標(biāo)識(shí)接口的請(qǐng)求方式(GET、POST、PUT、DELETE 等等)。

圖 5. Swagger 接口列表界面

接口調(diào)用

如下圖所示，點(diǎn)擊接口展開(kāi)后頁(yè)面右上角的 Try it out 按鈕后，頁(yè)面會(huì)變成如圖所示：

圖 6. 接口詳情界面

SwaggerUI 會(huì)給我們自動(dòng)填充請(qǐng)求參數(shù)的數(shù)據(jù)結(jié)構(gòu)，我們需要做的只是點(diǎn)擊 Execute 即可發(fā)起調(diào)用

圖 7. 接口調(diào)用界面

Model

如下圖所示，SwaggerUI 會(huì)通過(guò)我們?cè)趯?shí)體上使用的 @ApiModel 注解以及 @ApiModelProperty 注解來(lái)自動(dòng)補(bǔ)充實(shí)體以及其屬性的描述和備注。

圖 8. 實(shí)體界面

相關(guān)注解說(shuō)明

在本文中我將給出一些 Swagger 中常用的注解以及其常用的屬性，并對(duì)其一一解釋，方便您查看。

Controller 相關(guān)注解

@Api: 可設(shè)置對(duì)控制器的描述。

表 1. @Api 主要屬性

注解屬性	類型	描述
tags	String[]	控制器標(biāo)簽。
description	String	控制器描述(該字段被申明為過(guò)期)

表 2. @ApiOperation 主要屬性

注解屬性	類型	描述
value	String	接口說(shuō)明
notes	String	接口發(fā)布說(shuō)明。
tags	Stirng[]	標(biāo)簽。
response	Class>	接口返回類型。
httpMethod	String	接口請(qǐng)求方式。

@ApiIgnore: Swagger 文檔不會(huì)顯示擁有該注解的接口。 @ApiImplicitParams: 用于描述接口的非對(duì)象參數(shù)集。 @ApiImplicitParam: 用于描述接口的非對(duì)象參數(shù)，一般與 @ApiImplicitParams 組合使用。

持續(xù)精彩請(qǐng)點(diǎn)擊小程序

總結(jié)

以上是生活随笔為你收集整理的swagger 动态设置版本号_如何快速玩转swagger的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。