[[388819]]

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

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

那么為了解決 Swagger 的這些問(wèn)題，我們需要使用一個(gè) Swagger 的增強(qiáng)工具來(lái)實(shí)現(xiàn)，而這個(gè)擴(kuò)展工具就是我們今天要重點(diǎn)介紹的 Knife4j，那 Knife4j 長(zhǎng)得是什么樣呢?我們一起來(lái)看，如下圖所示：

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

PS：Knife4j 支持中文和英文兩種語(yǔ)言展示，對(duì)于國(guó)內(nèi)的小伙伴來(lái)說(shuō)，可讀性非常的高(因?yàn)槎际侵形牡穆?。

Knife4j 功能介紹

1.搜索功能

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

2.離線文檔下載

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

3.接口過(guò)濾

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

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

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

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

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

Knife4j 使用配置

從上面的內(nèi)容可以看出 knife4j 的功能是很強(qiáng)大的，但令我更驚喜的是它的配置異常的簡(jiǎn)單，我們只需在已經(jīng)成功配置了 Swagger 的項(xiàng)目中，添加 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)過(guò)以上簡(jiǎn)單的依賴添加之后，無(wú)需配置任何內(nèi)容，我們就可以成功的使用 Knife4j 了。

訪問(wèn) Knife4j

我們可以通過(guò) http://localhost:8080/doc.html 訪問(wèn) Knife4j 的主頁(yè)，如下圖所示：

總結(jié)

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