[[388819]]

wagger 是開發(fā)中最常用的框架之一了，但 Swagger 本身又有很多不完善的地方，比如，在眾多的接口中查詢某一個接口，又或者是把所有的接口導出成 Word 格式等，都無法在 Swagger 中實現(xiàn)。

有人可能會問：為什么要把接口導成 Word 格式?這種場景還挺常見的，比如需要將接口對外部公司開放時，又或者是開發(fā)環(huán)境的網(wǎng)絡不能對外部開放(如專線，很多醫(yī)院都拉的是專線)，而生產(chǎn)環(huán)境的 Swagger 又是關閉狀態(tài)的時候，這時候只能依賴離線文檔來實現(xiàn)接口的調(diào)用了，而離線文檔最常用的格式便是 Word 了。

那么為了解決 Swagger 的這些問題，我們需要使用一個 Swagger 的增強工具來實現(xiàn)，而這個擴展工具就是我們今天要重點介紹的 Knife4j，那 Knife4j 長得是什么樣呢?我們一起來看，如下圖所示：

圖片從這個主頁可以看出，Knife4j 會將 Swagger 中設置的摘要信息(Docket)顯示在歡迎頁，Docket 的設置可以看我之前的文章，并且 Knife4j 還很貼心的提供了一個統(tǒng)計所有接口的功能，在歡迎頁的最下方我們可以很清楚的看到當前 POST 接口的數(shù)量，以及 GET 的接口的數(shù)量。

PS：Knife4j 支持中文和英文兩種語言展示，對于國內(nèi)的小伙伴來說，可讀性非常的高(因為都是中文的嘛)。

Knife4j 功能介紹

1.搜索功能

我覺得 Knife4j 最實用的一個功能就是“接口搜索”了，通過這個功能我們可以非常方便的找到我們需要的接口，如下圖所示：

2.離線文檔下載

Knife4j 提供了 4 種格式的離線文檔下載：Markdown、Html、Word、OpenAPI 等方式，如下圖所示：

3.接口過濾

可以通過 Knife4j 過濾某一類型的接口，比如過濾 GET 或者 POST 接口，如下圖所示：

4.全局參數(shù)設置

如果有公共的請求參數(shù)，我們可以通過 Knife4j 輕松搞定，如下圖所示：

5.更友好的接口調(diào)試

使用 Knife4j 可以更友好的實現(xiàn)接口調(diào)試，因為在使用 Knife4j 時，它會將必傳的參數(shù)以紅色邊框的方式顯示，這樣我們就直觀的區(qū)分開必填參數(shù)和非必填參數(shù)了，如下圖所示：

Knife4j 使用配置

從上面的內(nèi)容可以看出 knife4j 的功能是很強大的，但令我更驚喜的是它的配置異常的簡單，我們只需在已經(jīng)成功配置了 Swagger 的項目中，添加 Knife4j 的依賴即可，配置信息如下：

<!-- https://mvnrepository.com/artifact/com.github.xiaoymin/knife4j-spring-boot-starter --> 
<dependency> 
    <groupId>com.github.xiaoymin</groupId> 
    <artifactId>knife4j-spring-boot-starter</artifactId> 
    <version>3.0.2</version> 
</dependency> 

經(jīng)過以上簡單的依賴添加之后，無需配置任何內(nèi)容，我們就可以成功的使用 Knife4j 了。

訪問 Knife4j

我們可以通過 http://localhost:8080/doc.html 訪問 Knife4j 的主頁，如下圖所示：

總結(jié)

Swagger 作為非常歡迎的框架同時也存在著一些功能“缺陷”，那么為了彌補 Swagger 的不足，我們引入了 Knife4j 框架，使用 Knife4j 我們可以很方便的實現(xiàn)：接口搜索、離線文檔下載、全局參數(shù)設置、接口過濾和更加友好的接口測試等功能。然而和它的功能同樣令人驚訝的是它的配置，在使用 Knife4j 時，我們只需要在項目中添加它的引用，之后無需任何多余的操作就可以直接使用 Knife4j 了，簡直完美，所以你不來試一試嗎?