Spring Boot集成Springfox Swagger3和簡單應用
- 2021 年 2 月 26 日
- 筆記
- Spring Boot, 微服務
摘要：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("樓蘭胡楊", "//www.cnblogs.com/east7/", "[email protected]"))
.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()
* //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;
}
/**
* 示例地址 //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了，啟動項目後訪問//IP:port/your-app-root/swagger-ui/index.html可以看到我們的swagger文檔介面，其中，IP表示伺服器IP地址，port表示項目配置的埠號，your-app-root表示項目配置的根路徑。在我的項目中，其訪問路徑是//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。歡迎點贊閱讀，一同學習交流；若有疑問，請在文章下方留下你的神評妙論！
