一般在使用 Spring Boot 開發前後端分離專案的時候，都會用到 Swagger。Swagger 是一個規範和完整的框架，用於生成、描述、除錯和視覺化 RESTful 風格的 Web API 服務框架。
但隨著系統功能的不斷增加，介面數量的爆炸式增長，Swagger 的使用體驗就會變得越來越差，比如請求引數為 JSON 的時候沒辦法格式化，返回結果沒辦法摺疊，還有就是沒有提供搜尋功能。
剛好最近發現 Knife4j 彌補了這些不足，賦予了 Swagger 更強的生命力，於是就來給大家安利一波。
一、關於 Knife4j
Knife4j 的前身是 swagger-bootstrap-ui，是 springfox-swagger-ui 的增強 UI 實現。swagger-bootstrap-ui 採用的是前端 UI 混合後端 Java 程式碼的打包方式，在微服務的場景下顯得非常臃腫，改良後的 Knife4j 更加小巧、輕量，並且功能更加強大。
springfox-swagger-ui 的介面長這個樣子，說實話，確實略顯醜陋。
swagger-bootstrap-ui 增強後的樣子長下面這樣。單純從直觀體驗上來看，確實增強了。
改良後的 Knife4j 不僅在介面上更加優雅、炫酷，功能上也更加強大：後端 Java 程式碼和前端 UI 模組分離了出來，在微服務場景下更加靈活；更提供了專注於 Swagger 的增強解決方案。
官方文件：
碼雲地址：
示例地址：
二、整合 Swagger
為了對比 Knife4j 和 Swagger，我們先來整合體驗一把 Swagger。
第一步，在 pom.xml 中新增 springfox 的官方 Swagger 依賴：
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
第二步，新增 Swagger 的 Java 配置，只需要配置基本的 API 資訊和需要掃描的類路徑即可。
@Configuration
public class SwaggerConfig {
@Bean
public Docket docket() {
Docket docket = new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo()).enable(true)
.select()
//apis： 新增swagger介面提取範圍
.apis(RequestHandlerSelectors.basePackage("com.codingmore.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("程式設計貓學習網站的 admin 管理端 API")
.description("codingmore")
.contact(new Contact("沉默王二&石磊", "https://tobebetterjavaer.com", "983436076@qq.com"))
.version("1.0")
.build();
}
}
第二步，訪問 API 文件，訪問地址如下所示：
在專案路徑後面新增上 swagger-ui 就可以了。
在 Controller 類中，可以看到常見的 Swagger 註解 @Api 和 @ApiOperation：
@Controller
@Api(tags = "文章 ")
@RequestMapping("/posts")
public class PostsController {
@RequestMapping(value = "/delete", method = RequestMethod.GET)
@ResponseBody
@ApiOperation("刪除")
public ResultObject<String> delete(long postsId) {
return ResultObject.success(postsService.removePostsById(postsId) ? "刪除成功" : "刪除失敗");
}
}
-
@Api 註解用在類上，該註解將一個 Controller 類標記位一個 Swagger 資源（API）。預設情況下，Swagger 只會掃描解析具有 @Api 註解的類。
-
@ApiOperation 註解用在方法上，該註解在指定的方法上，對一個方法進行描述。
Swagger 還有很多其他的註解，比如說 @ApiParam、@ApiResponses 等等，這裡就不再一一說明。
三、整合 Knife4j
Knife4j 完全遵循了 Swagger 的使用方式，所以可以無縫切換。
第一步，在 pom.xml 檔案中新增 Knife4j 的依賴（不需要再引入 springfox-boot-starter）。
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<!--在引用時請在maven中央倉庫搜尋3.X最新版本號-->
<version>3.0.2</version>
</dependency>
第二步，在 Java 配置類上新增 @EnableOpenApi 註解，開啟 Knife4j 增強功能。
@Configuration
@EnableOpenApi
public class SwaggerConfig {}
第三步，重新執行 Spring Boot 專案，訪問 API 文件，檢視效果。
如果專案中加了許可權認證的話，記得給 Knife4j 新增白名單。我的專案用的是 SpringSecurity，所以需要在 application.yml 檔案中新增。
secure:
ignored:
urls: #安全路徑白名單
- /doc.html
- /swagger-ui/**
- /swagger/**
- /swagger-resources/**
- /**/v3/api-docs
四、Knife4j 的功能特點
1）支援登入認證
Knife4j 和 Swagger 一樣，也是支援頭部登入認證的，點選「authorize」選單，新增登入後的資訊即可保持登入認證的 token。
如果某個 API 需要登入認證的話，就會把之前填寫的資訊帶過來。
2）支援 JSON 摺疊
Swagger 是不支援 JSON 摺疊的，當返回的資訊非常多的時候，介面就會顯得非常的臃腫。Knife4j 則不同，可以對返回的 JSON 節點進行摺疊。
3）離線文件
Knife4j 支援把 API 文件匯出為離線文件（支援 markdown 格式、HTML 格式、Word 格式），
使用 Typora 開啟後的樣子如下，非常的大方美觀。
4）全域性引數
當某些請求需要全域性引數時，這個功能就很實用了，Knife4j 支援 header 和 query 兩種方式。
之後進行請求的時候，就會把這個全域性引數帶過去。
5）搜尋 API 介面
Swagger 是沒有搜尋功能的，當要測試的介面有很多的時候，當需要去找某一個 API 的時候就傻眼了，只能一個個去拖動滾動條去找。
在文件的右上角，Knife4j 提供了文件搜尋功能，輸入要查詢的關鍵字，就可以檢索篩選了，是不是很方便？
目前支援搜尋介面的地址、名稱和描述。
五、尾聲
除了我上面提到的增強功能，Knife4j 還提供了很多實用的功能，大家可以通過官網的介紹一一嘗試下，生產效率會提高不少。
https://doc.xiaominfo.com/knife4j/documentation/enhance.html
如果專案中之前使用過 Swagger 生成介面文件，切換到 Knife4j 可以說是非常的絲滑，只需要兩步：
- 在 pom.xml 檔案中把
springfox-boot-starter替換為knife4j-spring-boot-starter； - 訪問地址由原來的
http://${host}:${port}/swagger-ui.html切換到http://${host}:${port}/doc.html，如果有許可權限制的話，記得開白名單。
本篇已收錄至 GitHub 上星標 1.4k+ star 的開源專欄《Java 程式設計師進階之路》，該專欄風趣幽默、通俗易懂，對 Java 愛好者極度友好和舒適?，內容包括但不限於 Java 基礎、Java 集合框架、Java IO、Java 併發程式設計、Java 虛擬機器、Java 企業級開發（Git、SSM、Spring Boot）等核心知識點。
https://github.com/itwanger/toBeBetterJavaer
star 了這個倉庫就等於你擁有了成為了一名優秀 Java 工程師的潛力。也可以戳下面的連結跳轉到《Java 程式設計師進階之路》的官網網址，開始愉快的學習之旅吧。
沒有什麼使我停留——除了目的，縱然岸旁有玫瑰、有綠蔭、有寧靜的港灣，我是不繫之舟。