一般在使用 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", "[email protected]"))
.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 程序員進階之路》的官網網址，開始愉快的學習之旅吧。
沒有什麼使我停留——除了目的，縱然岸旁有玫瑰、有綠蔭、有寧靜的港灣，我是不繫之舟。