knife4j是為Java MVC框架集成Swagger生成Api文檔的增強解決方案,前身是swagger-bootstrap-ui,取名kni4j是希望它能像一把匕首一樣小巧,輕量,並且功能強悍!
knife4j的前身是swagger-bootstrap-ui，為了契合微服務的架構發展,由於原來swagger-bootstrap-ui采用的是后端Java代碼+前端Ui混合打包的方式,在微服務架構下顯的很臃腫,因此項目正式更名為knife4j。
目前項目主要的模塊如下：
此示例根據官方文檔介紹演示。
核心功能
該UI增強包主要包括兩大核心功能：文檔說明 和 在線調試
-
文檔說明：根據Swagger的規范說明，詳細列出接口文檔的說明，包括接口地址、類型、請求示例、請求參數、響應示例、響應參數、響應碼等信息，使用swagger-bootstrap-ui能根據該文檔說明，對該接口的使用情況一目了然。
-
在線調試：提供在線接口聯調的強大功能，自動解析當前接口參數,同時包含表單驗證，調用參數可返回接口響應內容、headers、Curl請求命令實例、響應時間、響應狀態碼等信息，幫助開發者在線調試，而不必通過其他測試工具測試接口是否正確,簡介、強大。
UI增強
同時，swagger-bootstrap-ui在滿足以上功能的同時，還提供了文檔的增強功能，這些功能是官方swagger-ui所沒有的，每一個增強的功能都是貼合實際,考慮到開發者的實際開發需要,是比不可少的功能，主要包括：
-
個性化配置：通過個性化ui配置項，可自定義UI的相關顯示信息
-
離線文檔：根據標准規范，生成的在線markdown離線文檔，開發者可以進行拷貝生成markdown接口文檔，通過其他第三方markdown轉換工具轉換成html或pdf，這樣也可以放棄swagger2markdown組件
-
接口排序：自1.8.5后，ui支持了接口排序功能，例如一個注冊功能主要包含了多個步驟,可以根據swagger-bootstrap-ui提供的接口排序規則實現接口的排序，step化接口操作，方便其他開發者進行接口對接
快速開始
相信使用過springboot的人大都知道和用過swagger，knife4j的使用方法和swagger幾乎一模一樣，沒有什么學習成本，不同的是展示的接口UI文檔更加友好和人性化。下面開始演示一個集成項目，首先來看pom文件依賴：
只引入一個knife4j的starter即可，不用其它依賴。springboot的配置文件和啟動類不用做任何特殊配置，使用knife4j需要一個swagger的配置類，這個配置類和以前使用swagger幾乎是一樣的：
可以看到，內容上沒什么變化，唯一的變化是類注解需要比原來的swagger多加一個 @EnableSwaggerBootstrapUi。這樣knife4j的所有配置都完成了，啟動項目可以訪問地址：
來看一下效果：
配置簡單接口
下面來配置一個簡單的接口，查看文檔的展示效果。首先來看接口的通用返回結果模型定義：
注意要在文檔上面展示，需要使用圖中的注解。這個通用結果的具體數據是一個泛型類型。下面我們定義一個具體的業務數據模型：
通過上面兩個的定義，接口的返回類型就搞定了，下面來看接口：
這個接口類中分為幾個部分需要注意，第一是類上面的@Api注解，描述了整個類的接口分類含義。還有一個是每個接口上面的 @ApiImplicitParams 注解，定義了接口的所有參數。還有@ApiResponses注解，定義了返回時，所有狀態碼所代表的的含義，最后是@ApiOperation注解，描述了單個接口本身的功能。
定義接口完成后，我們來重啟項目，查看文檔的效果：
首頁上面有一些變化，左側列表多了HelloController類的整體描述欄目，我們點開這個欄目，可以看到類中定義的所有接口：
點擊這個接口，看到右側非常詳細的接口文檔：
上圖中展示的是接口地址，接口類型，接口描述和詳細的入參描述，下面的相應狀態展示了我們定義的兩種狀態類型，還有接口的回參也非常詳細的列了出來：
文字描述類型，數據結構，類型都有，還有響應示例，可以說非常清晰了。個人認為這種展示效果比原來的swagger要友好很多。
右側還有調試功能，可以直接使用來測試接口：
在左側的文檔管理中，還可以設置全局參數，支持類似jwt的帶權限的測試：
對文檔還可以進行個性化設置：
說明
上面簡單介紹和演示了knife4j，這個starter不僅支持swagger-bootstrap-ui，原始的swagger-ui還是可以使用的:
有些更加喜歡原始風格的同學可以看這個頁面。另外，swagger有很多注解，可以使文檔展示的信息更加完善和友好，大家可以自行嘗試和學習。
作者：郭藝賓
鏈接：https://www.jianshu.com/p/48d9473de9c8
來源：簡書
著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請注明出處。