SprongBoot3整合Knife4j

大家好，我是曉凡。

寫在前面

在上一篇文章，我們詳細介紹了SpringBoot3 怎麼整合SpringDoc實現線上介面文檔。但是，有不少小伙伴

都覺得介面界面太醜了。有沒有什麼更美觀一點的UI界面呢？

當然是有的了，畢竟這是一個看臉的時代，Knife4j 這不來了麽。

一、界面比較

這兒我們將上一篇文章使用swagger UI 和Knife4j UI做一個比較，哪個好看就不用我多說了吧。

① swaggerUI界面

②Knife4j UI界面

二、Knife4j 是什麼？

Knife4j 是一個為 Java 項目生成和管理 API 文檔的工具。實際上，它是 Swagger UI的一個增強工具集，

旨在讓 Swagger 生成的 API線上文檔更加優雅、美觀、強大。

① 官方地址

http://knife4j.net/

②文檔地址

https://doc.xiaominfo.com/docs/quick-start

三、為什麼要使用Knife4j

使用Knife4j主要有以下優點，就問哪個不吸引我們呢？

• 美觀的UI：相比於原生 Swagger UI，Knife4j 提供了更加人性化和美觀的界面設計
• 豐富的文檔交互功能：支持線上調試、請求參數動態輸入、介面排序等
• 個性化配置：可自定義 API 文檔的界面風格，實現文檔界面的個性化展示

四、Knife4j版本介紹

目前，我們使用的SpringBoot 版本主要是2和3,不同的boot版本需要適配不同版本的Knife4j.

通過這一小節，我們將在項目中選擇合適的Knife4j版本

4.1 Knife4j的前世今生

在更名為Knife4j之前,原來的名稱是叫swagger-bootstrap-ui，這是兩種不一樣風格的Ui,區別如下

Knife4j從開源至今,目前主要經歷版本的變化，分別如下：

4.2 Spring Boot版本相容性

如果你不考慮使用Knife4j提供的服務端增強功能，引入Knife4j的純Ui版本沒有任何限制。只需要考慮不同的規範即可

五、快速開始

通過上面的介紹，相信你已經對Knife4j 有了整體的認識，接下來我們就使用SpringBoot3快速整合Knife4j。

我們這選用的環境如下

• jdk17
• SpringBoot3.3.1
• knife4j 4.4.0
• OpenAPI3協議規範

5.1 新建一個web項目

建一個名為knife4j-spring-boot3-demo 的web項目，項目結構如下

5.2 添加Knife4j 依賴

⚠️溫馨提示

我們這裡使用的是SpringBoot3

• Spring Boot 3 只支持OpenAPI3規範
• Knife4j提供的starter已經引用springdoc-openapi的jar，需註意避免jar包衝突
• JDK版本必須 >= 17

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
    <version>4.4.0</version>
</dependency>

5.3 新建hello介面

新建controller包，添加HelloController類，代碼如下

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
}

5.4 訪問Knife4j線上文檔

瀏覽器輸入：http://localhost:8080/doc.html 訪問線上介面文檔

六、Knife4j 常用配置

⚠️溫馨提示：

增強功能需要通過配置application.yml配置文件開啟增強，後面不再贅述，預設開啟

knife4j:
enable: true

6.1 項目配置

在application.yml中可以自定義api-docs和swagger-ui的訪問路徑。當然了，如果沒配置，預設就是下麵路徑

註：這兒還是相容swagger ui頁面展示

springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiezhr.knife4jspringboot3demo.controller

瀏覽器輸入：http://localhost:8080/swagger-ui/index.html 可按照原來ui來顯示

6.2 配置介面文檔基本信息

① 配置介面基本信息

新建一個config包--->併在包下建立一個Knife4jConfig配置類

② 配置介面文檔基礎信息

這兒我們可以配置介面文檔標題、介面文檔版本信息、介面文檔描述信息、介面文檔聯繫人信息，介面文檔license許可證信息

我們只需在配置類中添加如下代碼即可

@Configuration
public class Knife4jConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                // 配置介面文檔基本信息
                .info(this.getApiInfo())
                ;
    }

    private Info getApiInfo() {
        return new Info()
                // 配置文檔標題
                .title("SpringBoot3集成Knife4j")
                // 配置文檔描述
                .description("SpringBoot3集成Knife4j示例文檔")
                // 配置作者信息
                .contact(new Contact().name("程式員曉凡").url("https://www.xiezhrspace.cn").email("[email protected]"))
                // 配置License許可證信息
                .license(new License().name("Apache 2.0").url("https://www.xiezhrspace.cn"))
                // 概述信息
                .summary("SpringBoot3集成Knife4j示例文檔aaa")
                .termsOfService("https://www.xiezhrspace.cn")
                // 配置版本號
                .version("2.0");
    }
}

瀏覽器輸入：http://localhost:8080/doc.html 訪問顯示如下

6.3 i18n國際化

Knife4j提供了i18n的支持,支持的語言主要包含2種：中文(zh-CN)、英文(en-US)。預設是中文

①通過下拉框選擇

通過訪問doc.html打開文檔界面,可以在文檔的右上角看到語言的選擇,如下圖：

② 通過文檔地址也可以選擇

• 中文：http://host:port/doc.html#/home/zh-CN
• 英文：http://host:port/doc.html#/home/en-US

另外,如果你是使用了knife4j提供的增強功能,你也可以這樣訪問

• 中文：http://host:port/doc.html#/plus/zh-CN
• 英文：http://host:port/doc.html#/plus/en-US

③ 通過application.yml配置文件設置

knife4j:
  enable: true
  setting:
    language: zh_cn

6.4 介面添加作者

介面代碼如下,我們給hello介面添加作者“張三”

@ApiOperationSupport(author = "張三")
@GetMapping("/hello")
public String hello(){
    return "hello";
}

6.5 自定義文檔

有時候在OpenAPI不足以滿足介面說明的情況下,我們可以通過.md格式文件擴充系統文檔說明

①添加自定義文檔

我們可以在當前項目中添加多個文件夾，文件夾中存放.md格式的markdown文件,每個.md文檔代表一份自定義文檔說明。

這裡，我們在預設組default 下麵添加介面簽名認證文檔說明.md和自定義文檔說明.md 兩個文檔，結構如下

每個.md文件中，Knife4j允許一級(h1)、二級(h2)、三級(h3)標題作為最終的文檔標題

比如，上面添加的自定義文檔說明.md內容如下

# 自定義文檔說明

## 效果說明

`knife4j`為了滿足文檔的個性化配置,添加了自定義文檔功能

開發者可自定義`md`文件擴展補充整個系統的文檔說明

開發者可以在當前項目中添加一個文件夾，文件夾中存放`.md`格式的markdown文件,每個`.md`文檔代表一份自定義文檔說明

**註意**：自定義文檔說明必須以`.md`結尾的文件,其他格式文件會被忽略

② 配置自定義文檔顯示

文檔添加好之後，我們在application.yml 添加如下配置信息

knife4j:
  documents:
    - group: default
      name: 其他文檔
      # 某一個文件夾下所有的.md文件
      locations: classpath:markdown/*

配置說明：

• group: 分組的名稱，這兒我們還沒有配置分組，所以預設的是default
• name: 界面呈現時菜單顯示
• locations: markdown文檔路徑

③ 前端界面呈現效果

上述信息配置好之後，在瀏覽器訪問doc.html 如下

6.6 訪問許可權控制

為了保證生產環境下介面服務安全，我們可以提供一個登陸界面的功能,只有輸入用戶名和密碼才能訪問

① 在application.yml 中添加如下配置

knife4j:
  enable: true
  basic:
    enable: true
    username: xiezhr
    password: 123456

②需要輸入正確的用戶名和密碼才能訪問

6.7 介面排序

使用Knife4j提供的增強註解@ApiOperationSupport中的order欄位可進行介面排序

HelloController 中有hello 和 getToken 兩個介面，我們要實現getToken介面顯示在前面，代碼如下

① 修改application.yml

springdoc:
  swagger-ui:
    operations-sorter: order

② 調整@ApiOperationSupport中的order

@RestController
public class HelloController {
    @ApiOperationSupport(author = "張三",order = 2)
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @ApiOperationSupport(author = "李四" ,order = 1)
    @GetMapping("/access-appid")
    public String getToken(){

        return "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
    }
}

③ 介面顯示順序如下

6.8 介面分組

為了演示API分組，我們在controller包下麵再建立admin包和common包，包下分別添加AdminController和CommonController介面類,結構及代碼如下

① AdminController類

@RequestMapping("admin")
@RestController
public class AdminController {

    @GetMapping("/access-appid")
    public String getToken(){

        return "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
    }
}

② CommonController 類

@RequestMapping("common")
@RestController
public class CommonController {

    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }

    @GetMapping("/hi")
    public String Hi(){
        return "Hi 程式員曉凡";
    }
}

在預設情況（沒有分組）的情況下，所有包下介面都顯示在一一個預設組下麵，如/common/* 和/admin/* 訪問路徑下的介面都顯示在一起，如下圖所示

這時，如果/common/* 下的介面比較多，/admin/* 下的介面也比較多，界面上顯示就很混亂

解決辦法就是添加分組信息，這裡有兩種配置方法

① 通過application.yml配置 admin分組和common 兩個分組

springdoc:
  group-configs:
    - group: 'admin'
      paths-to-match: '/admin/**'
      packages-to-scan: com.xiezhr.knife4jspringboot3demo.controller
    - group: 'common'
      paths-to-match: '/common/**'
      packages-to-scan: com.xiezhr.knife4jspringboot3demo.controller

② 通過配置類Knife4jConfig添加兩個分組

@Configuration
public class SpringDocConfig {
  // 此處省去其他配置信息......
    
    @Bean("common")
    public GroupedOpenApi webGroupApi() {
        return GroupedOpenApi.builder().group("common")
                .pathsToMatch("/common/**")
                .build();
    }

    @Bean("admin")
    public GroupedOpenApi adminGroupApi() {
        return GroupedOpenApi.builder().group("admin")
                .pathsToMatch("/admin/**")
                .build();
    }

}

以上兩種配置時等效的，再訪問:http://localhost:8080/doc.html 顯示如下

6.9 動態請求參數

在某些特定的情況下如果後端定義的是一種Map結構,或者是參數並沒有定義聲明,而希望也能達到一種動態添加參數進行調試的結果,這種體驗有點類似於postman

① 開啟動態參數配置

knife4j:
  enable: true
  setting:
  # 開啟動態請求參數，true-開啟，false-關閉
    enable-dynamic-parameter: true

配置完後，開啟動態請求這個會勾上

② 添加動態參數調試

6.10 過濾請求參數

通常我們在開發介面時,比如一個新增介面和一個修改介面,修改介面需要傳遞主鍵id、而新增介面則不需要傳遞此屬性,但大部分情況,我們只寫一個Model類,此時在新增介面時顯示主鍵id會顯得很多餘.

使用自定義增強註解ApiOperationSupport中的ignoreParameters屬性,可以強制忽略要顯示的參數.

忽略的規則如下：

• 例如新增介面時,某實體類不需要顯示Id,即可使用該屬性對參數進行忽略.ignoreParameters={"id"}
• 如果存在多個層次的參數過濾,則使用名稱.屬性的方式,例如 ignoreParameters={"uptModel.id","uptModel.uptPo.id"},其中uptModel是實體對象參數名稱,id為其屬性,uptPo為實體類,作為uptModel類的屬性名稱
• 如果參數層級只是一級的情況下,並且參數是實體類的情況下,不需要設置參數名稱,直接給定屬性值名稱即可
• 如果實體類屬性中是通過List這種數組的方式,那麼過濾規則會有所不同,在屬性後面需要追加一個下標[0]，ignoreParameters={"uptModel.uptPo[0].id"}

在介面過濾時,主要有兩種情況

6.10.1 表單參數

我們在使用實體類直接作為參數時,在我們的ui界面中是不會顯示參數名稱的,此時可以直接使用實體的屬性名稱進行參數忽略，例如如下代碼：

表單類型的請求是不需要添加參數名的

@ApiOperation(value = "新增Model介面1")
@ApiOperationSupport(ignoreParameters = {"id","orderDate.id"})
@PostMapping("/insertMode1l")
public Rest<UptModel> insertModel1(UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}

實體類UptModel.java文件代碼

public class UptModel {

    @ApiModelProperty(value = "主鍵id")
    private String id;

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "郵箱")
    private String email;

    @ApiModelProperty(value = "訂單信息")
    private OrderDate orderDate;
}

此時，最終過過濾掉UptModel的屬性id和屬性orderDate類中的id屬性,不在界面顯示.

6.10.2 JSON參數

如果請求參數是使用JSON的方式

代碼如下：

@ApiOperation(value = "新增Model介面")
@ApiOperationSupport(ignoreParameters = {"uptModel.id","uptModel.name","uptModel.orderDate.id"})
@PostMapping("/insertModel")
public Rest<UptModel> insertModel(@RequestBody UptModel uptModel){
    Rest<UptModel> r =new Rest<>();
    r.setData(uptModel);
    return r;
}

此時如果要過濾id的話,需要指定帶上參數名稱uptModel

最終忽略的值為ignoreParameters = {"uptModel.id","uptModel.name","uptModel.orderDate.id"}

6.11 包含請求參數

時候需要忽略的參數太多時,我們需要寫很多的忽略參數屬性,此時,一個與忽略參數對立取反的特性就顯得很有幫助了

使用自定義增強註解ApiOperationSupport中的includeParameters屬性,可以強制包含要顯示的參數.去除多餘的參數

6.12 自定義Host

不同的網路環境,可以通過配置該屬性,方便的進行調試

通過配置application.yml

knife4j:
  enable: true
  setting:
    # 是否啟用Host
    enable-host: true
    # 啟用Host後地址，例如：http://192.168.0.111:8080
    enable-host-text: "http://192.168.0.111:8080"

6.13 全局參數

Knife4j 提供全局參數設置功能，例如：我們可以設置全局token參數

全局參數功能主要提供兩種參數類型：

• query(表單)
• header(請求頭)

設置方法如下

6.14 自定義主頁內容

可以提供一個Markdown文件來自定義顯示Home主頁的顯示內容，通過配置yml來進行開啟，配置文件如下

knife4j:
  enable: true
  setting:
    enable-home-custom: true
    home-custom-path: classpath:markdown/home.md

• enable-home-custom:該屬性為Boolean值,預設false，如果開發者要自定義主頁內容,該選項設置為true
• home-custom-path:提供一個主頁的Markdown文件位置

我們markdown目錄下添加home.md 文檔，並添加內容之後，最終界面顯示如下

6.15 自定義Footer

Knife4j 支持自定義界面底部Footer內容，可以更改為公司或者產品介紹等信息

未自定義前

通過設置application.yml後

knife4j:
  enable: true
  setting:
    enable-footer: true
    enable-footer-custom: true
    footer-custom-content: Apache License 2.0 | Copyright  2019-[程式員曉凡](https://www.xiezhrspace.cn)

七、其他功能

7.1 導出離線文檔

使用swagger的時候，導出一份精細的文檔，需要很繁瑣的步驟，集成了knife4j之後，導出文檔變得很簡單

而且還可以導出不同格式的文檔

7.2 導出postman

我們還可以將介面信息複製然後導出到postman工具進行調試

具體操作如下

7.3 生成前端調用代碼

八、小結

SpringBoot3 整合knife4j其實非常簡單，界面相對於swagger UI 確實美觀了不少。文章只列舉了常用功能，如果小伙伴有特殊的需求，可以瀏覽官方文檔，官方文檔還是非常詳細的。

作者也給出了各種場景的實戰demo: https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

SpringBoot各種版本的整合都有案例

本期內容到這兒就結束了 ★,°:.☆(￣▽￣)/$:.°★ 。 希望對您有所幫助

我們下期再見 (●'◡'●) ヾ(•ω•`)o

本文來自博客園，作者：程式員曉凡，轉載請註明原文鏈接：https://www.cnblogs.com/xiezhr/p/18278808