當(dāng)前位置：首頁(yè) > 编程资源 > 编程问答 >内容正文

编程问答

springboot快速集成swagger

發(fā)布時(shí)間：2023/12/13 编程问答 41 豆豆

生活随笔收集整理的這篇文章主要介紹了 springboot快速集成swagger 小編覺(jué)得挺不錯(cuò)的,現(xiàn)在分享給大家,幫大家做個(gè)參考.

今天技術(shù)總監(jiān)說(shuō)：小明，我們本次3.0改造，使用swagger2.0作為前后端分離的接口規(guī)范，它可以一鍵生成前后端的API,一勞永逸……小明：？？？

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：基于瀏覽器的編輯器，我們可以使用它編寫我們 OpenAPI 規(guī)范。

Swagger UI：它會(huì)將我們編寫的 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)編寫的，相信大家也都知道這種方式很難保證文檔的及時(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)建完成后，為了方便后面代碼的編寫您可以將其導(dǎo)入到您喜歡的 IDE 中，我這里選擇了 Intelli IDEA 打開(kāi)。

添加依賴

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

清單 1. 添加 Web 依賴

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

編寫接口

首先我們創(chuàng)建三個(gè)包：cn.itweknow.sbswagger.controller、cn.itweknow.sbswagger.testcontroller 以及 cn.itweknow.sbswagger.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 依賴

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

Java 配置

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

清單 4. Swagger Java 配置

@Configuration @EnableSwagger2 public class SwaggerConfig {@Beanpublic 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 依賴

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

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

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

圖 1. Swagger UI

點(diǎn)擊查看大圖

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

高級(jí)配置

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

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

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

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

通過(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; }

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

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

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

文檔信息配置，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. 配置文檔信息

@Bean public 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://itweknow.cn，歡迎大家訪問(wèn)。","API V1.0","Terms of service",new Contact("名字想好沒(méi)", "https://itweknow.cn", "gancy.programmer@gmail.com"),"Apache", "http://www.apache.org/", Collections.emptyList()); }

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

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

點(diǎn)擊查看大圖

接口過(guò)濾

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

@ApiIgnore 注解。

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

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

@ApiIgnore public boolean delete(@PathVariable("id") int id)

在 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 文檔界面

點(diǎn)擊查看大圖

自定義響應(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)消息

點(diǎn)擊查看大圖

Swagger UI 的使用

接口查看

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

圖 5. Swagger 接口列表界面

點(diǎn)擊查看大圖

接口調(diào)用

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

圖 6. 接口詳情界面

點(diǎn)擊查看大圖

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

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

點(diǎn)擊查看大圖

Model

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

圖 8. 實(shí)體界面

點(diǎn)擊查看大圖

結(jié)束語(yǔ)

在本教程中，我們學(xué)會(huì)了如何使用 Swagger 2 來(lái)生成 Spring Boot REST API 的文檔。我們還研究了如何過(guò)濾 API、自定義 HTTP 響應(yīng)消息以及如何使用 SwaggerUI 直接調(diào)用我們的 API。您可以在 Github 上找到本教程的完整實(shí)現(xiàn)，這是一個(gè)基于 IntelliJ IDEA 的項(xiàng)目，因此它應(yīng)該很容易導(dǎo)入和運(yùn)行，當(dāng)然如果您想對(duì)本教程做補(bǔ)充的話歡迎發(fā)郵件給我 (mynamecoder@163.com) 或者直接在 GitHub 上提交 Pull Request。

參考資源

Spring 指南
Spring 主頁(yè)
Spring Boot 參考指南
Swagger 主頁(yè)
本文源碼地址

歡迎關(guān)注微信公眾號(hào)，獲取更多資源

轉(zhuǎn)載于:https://www.cnblogs.com/coderxx/p/10953726.html

總結(jié)

以上是生活随笔為你收集整理的springboot快速集成swagger的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

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

paramType	查詢參數(shù)類型，實(shí)際上就是參數(shù)放在那里。取值： path：以地址的形式提交數(shù)據(jù)，根據(jù) id 查詢用戶的接口就是這種形式傳參。 query：Query string 的方式傳參。 header：以流的形式提交。 form：以 Form 表單的形式提交。
dataType	參數(shù)的數(shù)據(jù)類型。取值： Long String
name	參數(shù)名字。
value	參數(shù)意義的描述。
required	是否必填。取值： true：必填參數(shù)。 false：非必填參數(shù)。

生活随笔

生活随笔

编程问答

springboot快速集成swagger

Swagger 簡(jiǎn)介

為什么要使用 Swagger

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

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

添加依賴

編寫接口

集成 Swagger2

添加依賴

Java 配置

驗(yàn)證

集成 Swagger UI

添加依賴

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

高級(jí)配置

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

接口過(guò)濾

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

Swagger UI 的使用

接口查看

接口調(diào)用

Model

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

Controller 相關(guān)注解

接口相關(guān)注解

Model 相關(guān)注解

結(jié)束語(yǔ)

參考資源

歡迎關(guān)注微信公眾號(hào)，獲取更多資源

總結(jié)