knife4j

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的所有配置都完成了

軟件	版本	增強注解	說明
knife4j	<=2.0.0	@EnableSwaggerBootstrapUi	?
knife4j	>=2.0.1	@EnableKnife4j	后續版本不會再更改

啟動項目可以訪問地址：

• http://localhost:8080/doc.html?plus=1

來看一下效果：

配置簡單接口

下面來配置一個簡單的接口，查看文檔的展示效果。首先來看接口的通用返回結果模型定義：

注意要在文檔上面展示，需要使用圖中的注解。這個通用結果的具體數據是一個泛型類型。下面我們定義一個具體的業務數據模型：

通過上面兩個的定義，接口的返回類型就搞定了，下面來看接口：

這個接口類中分為幾個部分需要注意，第一是類上面的@Api注解，描述了整個類的接口分類含義。還有一個是每個接口上面的 @ApiImplicitParams 注解，定義了接口的所有參數。還有@ApiResponses注解，定義了返回時，所有狀態碼所代表的的含義，最后是@ApiOperation注解，描述了單個接口本身的功能。

定義接口完成后，我們來重啟項目，查看文檔的效果：

首頁上面有一些變化，左側列表多了HelloController類的整體描述欄目，我們點開這個欄目，可以看到類中定義的所有接口：

點擊這個接口，看到右側非常詳細的接口文檔：

上圖中展示的是接口地址，接口類型，接口描述和詳細的入參描述，下面的相應狀態展示了我們定義的兩種狀態類型，還有接口的回參也非常詳細的列了出來：

文字描述類型，數據結構，類型都有，還有響應示例，可以說非常清晰了。個人認為這種展示效果比原來的swagger要友好很多。

右側還有調試功能，可以直接使用來測試接口：

在左側的文檔管理中，還可以設置全局參數，支持類似jwt的帶權限的測試：

對文檔還可以進行個性化設置：

說明

上面簡單介紹和演示了knife4j，這個starter不僅支持swagger-bootstrap-ui，原始的swagger-ui還是可以使用的:

有些更加喜歡原始風格的同學可以看這個頁面。另外，swagger有很多注解，可以使文檔展示的信息更加完善和友好，大家可以自行嘗試和學習。

坑處：
有個比較坑的地方，可能guava的版本是2.0以下會報錯com.google.common.collect.FluentIterable.concat(Ljava/lang/Iterable;Ljava/lang/Iterable;)Lcom/google

，解決方法是引入高版本

<dependency><groupId>com.google.guava</groupId><artifactId>guava</artifactId><version>20.0</version>
</dependency>

?