摘要：Springfox Swagger可以動態生成 API 介面供前後端進行互動和線上除錯介面，Spring Boot 框架是目前非常流行的微服務框架，所以，在Spring Boot 專案中整合Springfox非常有意義。介紹Spring Boot整合Springfox Swagger3及swagger的簡單應用。
§前言
Swagger是什麼？官方說法：Swagger是一個規範和完整的框架，用於建立、描述、除錯和視覺化 RESTful 風格的 Web 服務。通俗地說，Swagger 是一個主要用來線上建立文件的外掛，主要用來高質量地動態生成 API 介面供前後端進行互動和線上除錯介面，如果不生成的話就需要寫靜態文件來互動，那樣不僅速度慢而且不容易修改。發現了痛點就要尋找解決方案，故Swagger應運而生。
Springfox Swagger是Spring 基於swagger規範，可以將基於SpringMVC和Spring Boot專案的原始碼自動生成JSON格式的描述檔案。本身不是屬於Swagger官網提供的。Spring Boot 框架是目前非常流行的微服務框架，所以，在Spring Boot 專案中整合Springfox非常有意義，可以保證及時更新API文件，降低前後端溝通成本，提高系統迭代效率。
本文所用軟體開發環境如下：
♦ java version 13.0.1
♦ IntelliJ IDEA 2019.3.2 (Ultimate Edition)
♦ Spring Boot 2.3.1.RELEASE
§Spring Boot 整合 Springfox Swagger3
若想為Spring Boot專案新增無需任何配置的springfox，需引入其maven依賴庫：
<!--整合 springfox swagger3 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
為了便於管理API文件，建議編寫一個Swagger配置類，這裡的配置類如下：
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;
/**
* Swagger 配置類
*
* @author Wiener
* @date 2021/2/26
*/
@EnableOpenApi
@Configuration
public class SwaggerConfig {
//讀取application.properties 檔案設定的是否開啟swagger屬性，正式環境一般需要關閉
@Value(value = "${swagger.enabled}")
Boolean swaggerEnabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.OAS_30).apiInfo(apiInfo())
// 是否開啟swagger
.enable(swaggerEnabled).select()
// 過濾條件，掃描指定路徑下的檔案
.apis(RequestHandlerSelectors.basePackage("com.eg.wiener.controller"))
//只保留/user/*風格的路徑，大家可以除錯一下
// .paths(PathSelectors.ant("/user/*"))
// 指定路徑處理，PathSelectors.any()代表不過濾任何路徑
.paths(PathSelectors.any())
.build().pathMapping("/");
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot整合Springfox Swagger示例")
.description("樓蘭胡楊")
// 開發者資訊
.contact(new Contact("樓蘭胡楊", "https://www.cnblogs.com/east7/", "wienerXXX@163.com"))
.version("1.0.0")
.build();
}
}
註解@EnableOpenApi用於開啟Swagger的自動配置，如果沒加的話，自然而然也就看不到後面的swagger UI皮膚了。通過select()函式返回一個ApiSelectorBuilder例項，用來控制哪些介面暴露給Swagger UI皮膚；在 Docket 上新增篩選條件。Docket 類提供了 apis() 和 paths() 兩個方法來幫助我們在不同級別上過濾介面：
- apis() ：通過指定掃描路徑的方式，讓 Swagger 只去某些路徑下面掃描檔案。
- paths() ：通過篩選 API 的 url 進行過濾。
在上面的Swagger 配置類SwaggerConfig中，我們定義了 Docket 例項的 apis() 和 paths()，那麼，swagger介面文件介面將只會展示包com.eg.wiener.controller中的API。關於PathSelectors.ant()的用法，各位同仁可以除錯一下，由於時間有限，未曾驗證是否可用。
另一種解決方案就是使用@ApiIgnore註解遮蔽某些API。如果想在API文件中遮蔽掉某個介面，那麼只需要在這個介面上加上@ApiIgnore 即可。
豐富文件內容
在完成了上述配置後，已經算是初步整合Springfox Swagger3，可以啟動服務檢視API文件內容了。但是這樣的文件主要針對請求本身，描述資訊的主要來源是函式的命名，對使用者並不友好，我們通常需要使用swagger註解增加一些說明文字來使得API文件內容更加豐滿。Swagger中常用的註解及其說明：
@Api：用在類上，說明該類的作用。
@ApiOperation：為API增加方法說明。
@ApiImplicitParams : 用在方法上包含一組引數說明。
@ApiImplicitParam：給方法入參增加說明。
@ApiResponses：用於表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應資訊
l code：數字，例如400
l message：資訊，例如"必填引數不可為空"
l response：丟擲異常的類
@ApiModel：描述一個Model的資訊（一般用在請求引數無法使用@ApiImplicitParam註解進行描述的時候）
l @ApiModelProperty：描述一個model的屬性
案例分析
修改API實體類User，新增swagger註解：
@Setter
@Getter
@ToString
@ApiModel("使用者實體")
public class User implements Serializable {
private static final long serialVersionUID = -8842370047277749376L;
@ApiModelProperty("使用者 id")
private Long id;
@ApiModelProperty("使用者姓名")
private String userName;
private Integer age;
private String address;
private String mobilePhone;
private String remark;
public User() {
}
public User(Long id, String userName, Integer age) {
this.id = id;
this.userName = userName;
this.age = age;
}
}
在實體類使用註解@ApiModel和 @ApiModelProperty可以新增屬性備註，這些備註資訊將展示在swagger頁面的Schema中，效果如下：
在 controller 包下新建 UserController.java 類，通過在控制器類上增加 @Api 註解，可以給控制器新增標籤資訊。通過在介面方法上增加 @ApiOperation 註解來新增對介面的描述。關於swagger註解的更多資訊，這裡就不再闡述，需要的話，請去問問度娘。
/**
* @author Wiener
*/
@RestController
@RequestMapping("/user")
@Api(tags="使用者API")
public class UserController {
private static Logger logger = LoggerFactory.getLogger(UserController.class);
/**
* 同時使用 @RequestBody 與 @RequestParam()
* http://localhost:8087/wiener/user/addUser?token=IamToken
* @param user
* @param token
* @return
* @throws Exception
*/
@PostMapping("/addUser")
@ApiOperation(value="使用者新增")
public User addUser(@RequestBody User user, @RequestParam("token") String token) throws Exception {
user.setRemark(token);
return user;
}
/**
* 示例地址 http://localhost:8087/wiener/user/getUser?id=9996669
* @return
* @throws Exception
*/
@GetMapping("/getUser")
@ApiOperation(value="使用者查詢(ID)")
@ApiImplicitParam(name="id",value="查詢ID",required=true)
public User getUser(Long id) throws Exception {
logger.info("--------------------");
User user = new User();
user.setId(id);
user.setAddress("測試地址是 " + UUID.randomUUID().toString());
logger.info("類資訊： {}", user.getClass());
return user;
}
}
這個時候已經算是進一步整合Springfox-Swagger3了，啟動專案後訪問http://IP:port/your-app-root/swagger-ui/index.html可以看到我們的swagger文件介面，其中，IP表示伺服器IP地址，port表示專案配置的埠號，your-app-root表示專案配置的根路徑。在我的專案中，其訪問路徑是http://127.0.0.1:8087/wiener/swagger-ui/index.html，在瀏覽器訪問此URL進入如下文件介面：
使用 SwaggerUI訪問API
找到使用者查詢API getUser並進入介面詳情頁面，可以在詳情頁面右側看到** Try it out** 按鈕，單擊此按鈕即可進入介面呼叫介面，在id輸入框隨機輸入一個Long型別的數字，單擊執行即可請求getUser方法：
從API返回值可以得出結論：使用 Swagger UI 成功訪問了API，故整合整合Springfox Swagger3完畢。有底氣甩了Postman了，你認為呢？
§小結
Springfox既可以減少建立文件的工作量，同時介面文件又可以融合到程式碼之中去，使維護API文件和修改程式碼同步進行，讓我們在修改程式碼邏輯的同時方便的修改文件說明，這太酷了。另外，Swagger UI介面頁提供了強大的頁面測試功能來除錯每個RESTful API。歡迎點贊閱讀，一同學習交流；若有疑問，請在文章下方留下你的神評妙論！