前言

在之前的文章中，我們已經講了如何利用 Spring Boot 來集成 Swagger2，詳情可戳：Spring Boot 集成 Swagger2，構建強大的 API 文檔。但其實 Swagger2 中主流的 2.9.2 自 2018 年發布后就已經好久沒更新了，而在時隔兩年之后的 2020 年，Swagger3 終于發布了。

相比于之前的 Swagger2，Swagger3 無疑新添了更多的特點，而相對集中地，主要集中在如下幾點。

• 支持 OpenApi 3.0.3
• 兼容 Swagger2 的注釋，而且進一步豐富了 open API 3.0 的規范
• 支持 Webflux

既然 Swagger3 有了這么多的改變，那用法是不是還和 Swagger2 一樣呢？答案是：不一樣。

不過雖然兩者的使用方式不一樣，但是總體流程還是差不多了，只不過有些步驟有所小變動而已，只要你掌握了 Swagger2 的使用方法，那使用 Swagger3 起來就是需要注意小改動就行了。那接下來，我們就來看看，如何利用 Spring Boot 來集成 Swagger3，對我們的 Swagger2 進行一次升級！

Spring Boot 集成 Swagger

創建 Spring Boot 項目

同樣的，開始之前，我們需要創建一個簡單的 Spring Boot 項目，這里不展開講了，如果你對此還有所疑惑，可以先去熟悉下，這里建議參考我之前寫過的一篇文章：創建 Spring Boot 項目的 3 種方式。

項目創建成功之后，總體結構如下：

這里的 config、controller、entity 模塊是我后續加入的，所以不用理會，也就是說你創建好之后的項目是不包含這三個部分的，關于他們的用途，文章后續內容我會講到。

引入依賴

創建項目后，在 pom.xml 文件中引入 Swagger3 的相關依賴。回憶一下，我們集成 Swagger2 時，引入的依賴如下：

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

而在 Swagger3 中，我們不需要再引入兩個不同的依賴了，我們只需要引入一個依賴就足夠，具體引入的依賴如下：

<dependency><groupId>io.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version> </dependency>

而這部分，Swagger2 和 Swagger3 就有所不同了，Swagger2 需要添加兩項不同依賴，而 Swagger3 只用添加一項依賴就可以了。

構建 Swagger 配置類

為了統一管理 Swagger，這里還是推薦給 Swagger3 添加一個配置類。當然這里也可以根據自己的需求，可要可不要，但總體來說還是建議配置。

另外，在之前集成 Swagger2 的文章中，忘記了給大家說一點。平常在工作中，Swagger 的使用僅限于在開發環境，而在生產環境中，我們是要將其移除的。這里為了靈活管理，推薦大家在項目配置文件 application.yml 中添加關于 Swagger 開關的配置，比如這里我添加的配置如下，true 則代表開啟 Swagger，false 則表示關閉 Swagger。

swagger:enabled: true

配置完成之后，我們就需要在 Swagger 配置類中獲取 Swagger 開關的值了，關于具體用法就可以看下邊配置代碼。

package com.cunyu.springbootswagger3demo.config;import org.springframework.beans.factory.annotation.Value; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.oas.annotations.EnableOpenApi; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket;import java.util.ArrayList;/*** Created with IntelliJ IDEA.** @author : 村雨遙* @version : 1.0* @project : springboot-swagger3-demo* @package : com.cunyu.springbootswagger3demo.config* @className : SwaggerConfig* @createTime : 2022/1/6 14:19* @email : 747731461@qq.com* @微信 : cunyu1024* @公眾號 : 村雨遙* @網站 : https://cunyu1943.github.io* @description :*/@Configuration @EnableOpenApi public class SwaggerConfig {/*** 用于讀取配置文件 application.properties 中 swagger 屬性是否開啟*/@Value("${swagger.enabled}")Boolean swaggerEnabled;@Beanpublic Docket docket() {return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())// 是否開啟swagger.enable(swaggerEnabled).select()// 過濾條件，掃描指定路徑下的文件.apis(RequestHandlerSelectors.basePackage("com.cunyu.springbootswagger3demo.controller"))// 指定路徑處理，PathSelectors.any()代表不過濾任何路徑//.paths(PathSelectors.any()).build();}private ApiInfo apiInfo() {/*作者信息*/Contact contact = new Contact("村雨遙", "https://cunyu1943.github.io", "747731461@qq.com");return new ApiInfo("Spring Boot 集成 Swagger3 測試","Spring Boot 集成 Swagger3 測試接口文檔","v1.0","https://cunyu1943.github.io",contact,"Apache 2.0","http://www.apache.org/licenses/LICENSE-2.0",new ArrayList());} }

這里的配置和 Swagger2 大同小異，這里最大的區別在于加入了從配置文件中獲取 Swagger 開關的屬性。這里也可以選擇添加到 Swagger2 的配置類中，同樣通過配置文件來控制是否開啟 Swagger2。此外，還有就是 DocumentationType 屬性的不同了，Swagger2 中我們使用的是 SWAGGER_2，而在 Swagger3 中，我們使用的則是 OAS_30。其實點進去 DocumentationType 的源碼我們就可以發現，Swagger 已經是給我們定義好的，你用的是哪一個版本的 Swagger，那我們使用的屬性值應該選擇對應版本。三個版本的屬性值對應如下：

public static final DocumentationType SWAGGER_12 = new DocumentationType("swagger", "1.2"); public static final DocumentationType SWAGGER_2 = new DocumentationType("swagger", "2.0"); public static final DocumentationType OAS_30 = new DocumentationType("openApi", "3.0");

編寫實體類

完成上面的步驟之后，我們的 Swagger 就配置好了，接下來我們就添加一個接口來看看 Swagger3 和 Swagger2 的不同。

新建實體類

這里我以一個用戶類為實例，帶有 name、age 兩個屬性，也就是本文一開始項目結構截圖中 entity 包下的內容。

package com.cunyu.springbootswagger3demo.entity;import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.AllArgsConstructor; import lombok.Data; import lombok.NoArgsConstructor;/*** Created with IntelliJ IDEA.** @author : 村雨遙* @version : 1.0* @project : springboot-swagger3-demo* @package : com.cunyu.springbootswagger3demo.entity* @className : User* @createTime : 2022/1/6 11:17* @email : 747731461@qq.com* @微信 : cunyu1024* @公眾號 : 村雨遙* @網站 : https://cunyu1943.github.io* @description :*/@Data @AllArgsConstructor @NoArgsConstructor @ApiModel("用戶實體類") public class User {@ApiModelProperty(value = "姓名", required = true, example = "村雨遙")private String name;@ApiModelProperty(value = "年齡", required = true, example = "20")private Integer age; }

新建接口

這里寫了兩個接口，一個是直接傳參，另一種是通過利用創建的 User 實體類來傳輸，也就是項目結構中 controller 包中的內容。

package com.cunyu.springbootswagger3demo.controller;import com.cunyu.springbootswagger3demo.entity.User; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController;/*** Created with IntelliJ IDEA.** @author : 村雨遙* @version : 1.0* @project : springboot-swagger3-demo* @package : com.cunyu.springbootswagger3demo.controller* @className : UserController* @createTime : 2022/1/6 11:02* @email : 747731461@qq.com* @微信 : cunyu1024* @公眾號 : 村雨遙* @網站 : https://cunyu1943.github.io* @description :*/@Api(tags = "測試") @RestController @RequestMapping("/user") public class UserController {@ApiOperation("測試接口1")@PostMapping("/show1")public String show1(@ApiParam(value = "姓名", required = true, example = "村雨遙") @RequestBody String name) {return "hello," + name + ",welcome to springboot swagger3！";}@ApiOperation("測試接口2")@PostMapping("/show2")public String show2(@ApiParam(value = "用戶對象", required = true) @RequestBody User user) {return "hello," + user.getName() + ",welcome to springboot swagger3！";} }

查看并測試接口

啟動我們的項目，然后在瀏覽器中訪問如下地址，就可以訪問項目的接口文檔了。

http://localhost:8080/swagger-ui/index.html

訪問上面的地址后，如果出現下面的界面，則說明集成 Swagger3 就成功了。

這里也要注意一點，Swagger2 中的接口訪問地址是：

http://localhost:8080/swagger-ui.html

這里 Swagger2 和 Swagger3 是不同的，這里大家一定要注意，否則可能你繼續拿著 Swagger2 接口訪問地址來放到 Swagger3 項目中不適用。

點開具體接口，我們以直接傳參的接口來對比 Swagger3 和 Swagger2 的區別。第一張圖是在 Swagger3 中，第二張圖是在 Swagger2 中。這里可以發現，我們都是傳的一個 name 屬性，Swagger2 中會把我們接口中參數部分 Parameters 直接標識出來，而 Swagger3 中則不會，這里需要注意。

• Swagger2 中接口代碼

@ApiOperation(value = "有參接口") @PostMapping("demo") public String demo(@ApiParam(value = "姓名", required = true, example = "村雨遙") @RequestBody String name) {return "hello," + name; }

• Swagger3 中接口代碼

@ApiOperation("測試接口1") @PostMapping("/show1") public String show1(@ApiParam(value = "姓名", required = true, example = "村雨遙") @RequestBody String name) {return "hello," + name + ",welcome to springboot swagger3！"; }

此外，我們來看 Swagger3 中的另一個接口，這里我們傳遞的是一個用戶對象，接口中它將我們設置的默認值給傳了過來。下圖中第一張圖為 Swagger3 中的截圖，第二張圖為 Swagger2 中的截圖。同樣的，Swagger2 中的參數會在 Parameters 模塊標識出來，而 Swagger3 則不會標識。

還有一點值得注意的是，Swagger 中如果傳遞的部分是對象，那么 Swagger2 會在 Models 部分進行標識，而 Swagger3 中則是變成了 Schemas 部分，這也算是一個小變動吧。

最后，我們同樣來進行測試，測試方法同 Swagger2，點擊接口右上方的 Try it out，然后編輯參數的值，編輯完成后點擊下方的 Execute 即可查看接口調用結果。

Swagger2 VS Swagger3

經過上面的步驟，我們就完成了 Spring Boot 集成 Swagger3 的實例測試了，而經過對比，也總結出了 Swagger2 和 Swagger3 的區別主要體現在如下幾個方面：

所需依賴不同，Swagger2 需要添加兩個依賴，而 Swagger3 則只需要添加一個依賴；

啟用 Swagger 的注解不同，不知道大家有沒有發現，無論是 Swagger2 還是 Swagger3 中的配置類，其實都是有一個注解用來啟用 Swagger 的，不同之處在于 Swagger2 中用的是 @EnableSwagger2，而 Swagger3 中則用的是 @EnableOpenApi；

文檔摘要信息（Docket）文件類型不同，可以發現在 Swagger 的配置類中，Swagger2 用的是 SWAGGER_2，而 Swagger3 中則用的是 OAS_3；

Swagger UI 訪問地址不同，在 Swagger2 中，如果我們要訪問文檔地址，需要訪問 http://localhost:8080/swagger-ui.html，而在 Swagger3 中，則是訪問 http://localhost:8080/swagger-ui/index.html；

總結

以上就是本文的所有內容了，主要介紹了如何使用 Spring Boot 集成 Swagger3，并在此過程中對比了 Swagger2 和 Swagger3 的一些區別。總體來講，Swagger2 向 Swagger3 的升級還是比較平滑的。如果你已經掌握熟練使用 Swagger2，那么向 Swagger3 過度也很簡單，只需要注意上一部分中的一些主要區別就可以了。其他的用于描述接口的注解，還是可以按照 Swagger2 的方式使用，畢竟 Swagger3 向下兼容了 Swagger2。

代碼示例

最后，關于本文示例的代碼，我已經上傳至 GitCode，需要的小伙伴可以自取：

🎉 傳送門：https://gitcode.net/github_39655029/java-learning-demos

如果您覺得本文不錯，歡迎 Star 支持，您的關注就是我堅持不斷更新的動力！

總結

以上是生活随笔為你收集整理的Spring Boot 使用 Swagger3 生成 API 接口文档的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。