# 緣由 介面文件想必是許多開發小夥伴的噩夢，不僅要寫詳細，還要及時維護文件與後端程式碼保持一致，稍有沒及時更新介面文件，前端同學肯定會抱怨後端同學給的文件與實際情況不一致。  於是，引入了Swagger元件，它實現了程式碼即文件，後端只管寫程式碼，只需要通過幾個註解，會自動生成介面文件，前端同學可線上訪問。  但是，對介面審美有要求的前端同學，又吐槽Swagger原生介面太low了，而且功能還少。  有壓迫就有反抗，後端肯定不服，既然你嫌棄原生Swagger太low，那就給你開通超級VIP - knife4j。  # 原生Swagger Springboot整合Swagger，其實很簡單，主要是使用常用的幾個註解而已。因為在面試他人的過程中，還是有不少人沒使用過Swagger，所以這裡簡單介紹下。 首先在Spingboot工程中引入Swagger依賴，主要是2個，如下： ```xml io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.2 ``` 編寫Swagger配置類，配置項名都簡單易懂，可根據自己情況修改配置，注意一點是apis方法是指定要掃描的包路徑，一定要寫自己專案的。 ```java package com.nobody.config; ​ import java.util.ArrayList; import java.util.List; ​ 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.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; ​ @Configuration @EnableSwagger2 public class Swagger2Config { ​ @Value("${swagger.enable:true}") private boolean swaggerEnable; ​ @Bean public Docket createApi() { // 全域性引數 List pars = new ArrayList<>(); return new Docket(DocumentationType.SWAGGER_2).enable(swaggerEnable).apiInfo(apiInfo()) .select().apis(RequestHandlerSelectors.basePackage("com.nobody")) .paths(PathSelectors.any()).build().globalOperationParameters(pars); } ​ private ApiInfo apiInfo() { return new ApiInfoBuilder().title("XX服務後端API").description("XX服務專用API，其他系統請勿呼叫！") .version("1.0").termsOfServiceUrl("https://nobody.com") .contact(new Contact("陳皮", "https://nobody.com", "[email protected]")).build(); } } ``` 下面講解幾個常用的註解，以及如何使用，更多註解以及詳細使用可以參考[官方文件](https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X#quick-annotation-overview)。 1. @Api：作用於類上，標識此類是Swagger的資源。 2. @ApiOperation：主要作用於方法上，用於對一個介面進行說明。 3. @ApiParam：用於方法，引數，欄位上，用於對引數進行說明。 4. @ApiModel：作用於類上，主要用於實體類當介面引數時使用，對實體類進行說明。 5. @ApiModelProperty：作用於方法和欄位上，一般用於實體類的屬性說明。 ```java package com.nobody.dto; ​ import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; ​ /** * @Description * @Author Mr.nobody * @Date 2021/3/28 * @Version 1.0 */ @ApiModel(value = "管理員實體") @Data public class AdminDTO { @ApiModelProperty(value = "使用者ID", required = true, example = "1548w4dwf7as1a21cv4") private String personId; @ApiModelProperty(value = "使用者名稱", example = "陳皮") private String name; @ApiModelProperty(value = "使用者年齡", required = true, example = "18") private Integer age; } ``` ```java package com.nobody.controller; ​ import com.nobody.dto.AdminDTO; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.web.bind.annotation.*; ​ import java.util.ArrayList; import java.util.List; /** * @Description * @Author Mr.nobody * @Date 2021/3/27 * @Version 1.0 */ @Api(tags = {"管理員相關"}) @RestController @RequestMapping("admin") public class AdminController { ​ @ApiOperation(value = "新增管理員", notes = "注意：只有管理員許可權才能新增管理員", produces = "application/json", consumes = "application/json") @PostMapping("add") public AdminDTO add(@ApiParam(value = "引數體", required = true) @RequestBody AdminDTO adminDTO) { return adminDTO; } ​ @ApiOperation(value = "管理員列表", notes = "注意：只有管理員許可權才能獲取管理員列表", produces = "application/json") @GetMapping("list") public List list( @ApiParam(value = "頁碼，從1開始，1，2，3...", required = true, example = "1") @RequestParam Integer pageIndex, @ApiParam(value = "頁量", required = true, example = "10") @RequestParam Integer pageSize) { return new ArrayList<>(); } } ``` # Knife4J Knife4j的前身是swagger-bootstrap-ui,前身swagger-bootstrap-ui是一個純swagger-ui的ui面板專案。 目前已經發行的Knife4j版本，其本身已經引入了springfox，所以我們不需要再單獨引入Springfox的具體版本，否則會導致版本衝突。 注意，使用Knife4j2.0.6及以上的版本，SpringBoot的版本必須大於等於2.2.x。 Knife4J的使用極其簡單，因為Knife4J將其封裝成一個啟動器starter，一個可拔插式的元件，只需要引入starter依賴，即可使用。 ```xml com.github.xiaoymin

knife4j-spring-boot-starter 3.0.2 ``` 然後Swagger配置類還是和原生的一模一樣，即上面介紹過的Swagger2Config類，註解的使用也是和原生的完全一樣。只是專案啟動後，介面文件介面的訪問地址不一樣： - 原生Swagger：http://ip:port/swagger-ui.html#/ - Knife4J：http://ip:port/doc.html#/  是不是介面比原生的好看多了，還是保持著簡潔美觀，但是功能更多了。 當我們開啟一個介面，顯示的介面資訊更全了，而且分為3個頁面，文件，除錯和Open，​如下所示：   支援全域性搜尋，不用在眾多介面中一個一個查詢，節省時間。  Knife4j 提供全域性引數Debug功能，目前預設提供header(請求頭)、query(form)兩種方式的入參。新增全域性引數後，預設Debug除錯tab頁會帶上該引數。  Knife4j提供匯出4種格式的離線文件(Html/Markdown/Word/OpenAPI)  啟用個性化配置後,介面Tab標籤需關閉後重新開啟或者重新整理當前頁面。  更多Knife4J的詳細介紹，可以檢視官方介紹文件，很詳細​。​[https://xiaoym.gitee.io/knife4j/documentation/description.html](https://xiaoym.gitee.io/knife4j/documentation/description.html)