使用原生的swagger作為接口文檔，功能不夠強大，并且默認的ui比較簡陋，不符合大眾審美。所以實際開發(fā)中推薦使用knife4j對swagger進行增強。knife4j的地址：https://gitee.com/xiaoym/knife4j

推薦閱讀：Swagger及knife4j的基本使用詳解

基本使用

想要使用knife4j非常簡單，只要在Springboot項目中引入knife4j的依賴即可

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

注意：引入knife4j后會自動引入swagger相關依賴

所以無需再手動引入swagger相關依賴，否則會引起版本沖突，在使用knife4j的一些增強功能時會報錯

我們首先搭建springboot環(huán)境，創(chuàng)建2個Controller，用swagger相關注解來描述

// Controller1
@RestController
@RequestMapping("controller1")
@Api(tags = "應用1-Controller1")
public class Controller1 {
    @GetMapping("api1/{id}")
    @ApiOperation("api1")
    public void api1(@PathVariable("id") @ApiParam("用戶id") Long id) {

    }

    @PostMapping("api2")
    @ApiOperation("api2")
    public void api2(@RequestBody User user) {

    }
}

// Controller2
@RestController
@RequestMapping("controller2")
@Api(tags = "應用1-Controller2")
public class Controller2 {
    @GetMapping("api1/{id}")
    @ApiOperation("api1")
    public void api1(@PathVariable("id") @ApiParam("用戶id") Long id) {

    }

    @PostMapping("api2")
    @ApiOperation("api2")
    public void api2(@RequestBody User user) {

    }
}

// 實體類
@Data
@ApiModel("用戶實體")
public class User {
    @ApiModelProperty("姓名")
    private String name;
    @ApiModelProperty("年齡")
    private Integer age;
}

然后創(chuàng)建swagger配置類

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
    // 創(chuàng)建Docket存入容器，Docket代表一個接口文檔
    @Bean
    public Docket webApiConfig(){
        return new Docket(DocumentationType.SWAGGER_2)
                // 創(chuàng)建接口文檔的具體信息
                .apiInfo(webApiInfo())
                // 創(chuàng)建選擇器，控制哪些接口被加入文檔
                .select()
                // 指定@ApiOperation標注的接口被加入文檔
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .build();
    }

    // 創(chuàng)建接口文檔的具體信息，會顯示在接口文檔頁面中
    private ApiInfo webApiInfo(){
        return new ApiInfoBuilder()
                // 文檔標題
                .title("標題：用戶管理系統(tǒng)接口文檔")
                // 文檔描述
                .description("描述：本文檔描述了用戶管理系統(tǒng)的接口定義")
                // 版本
                .version("1.0")
                // 聯(lián)系人信息
                .contact(new Contact("baobao", "http://baobao.com", "baobao@qq.com"))
                // 版權
                .license("baobao")
                // 版權地址
                .licenseUrl("http://www.baobao.com")
                .build();
    }
}

此時啟動項目，訪問ip:端口/doc.html即可看到knife4j的文檔界面

增強功能

使用knife4j增強功能的前提是要在yaml配置中開啟增強模式

knife4j:
  enable: true

1.添加接口作者

swagger只能給整個文檔添加作者，不能針對某個接口單獨添加作者。knife4j中可以有2種方式給接口添加作者：

• 在Controller類上標注@ApiSupport(author = "作者名稱")，這樣整個Controller中的所有接口方法將被指定為該作者
• 在Controller接口方法上標注@ApiOperationSupport(author = "作者名稱")，這樣該接口被指定為該作者

如果@ApiSupport和@ApiOperationSupport同時指定了作者，那么方法級別的@ApiOperationSupport優(yōu)先級更高

2.生產環(huán)境關閉文檔

目前Springfox-Swagger以及Knife4j提供的資源接口包括如下：

swagger中要實現(xiàn)生產環(huán)境關閉文檔資源需要在配置類中進行編碼，判斷環(huán)境，比較麻煩。knife4j中只需要在對應環(huán)境的配置中添加配置即可

spring:
  profiles: prod # 指定為生產環(huán)境
knife4j:
  production: true # 開啟屏蔽文檔資源

此時只要以prod環(huán)境運行，就無法訪問到接口文檔

注意：如果正常非生產環(huán)境下不屏蔽文檔，那么引入了springsecurtiy或者自定義攔截器的時候，要排除掉上述表格中的文檔資源，否則在非屏蔽狀態(tài)下也將無法訪問到文檔資源

3.接口排序

接口排序的方式有2種：

針對不同Controller排序：Controller上標注@ApiSupport(order = 序號)

針對同一個Controller中的不同方法排序：同一個Controller不同接口方法上標注@ApiOperationSupport(order = 序號)

4.導出離線文檔

• markdown：導出當前邏輯分組下所有接口的Markdown格式的文檔
• Html：導出當前邏輯分組下所有接口的Html格式的文檔
• Word:導出當前邏輯分組下所有接口的Word格式的文檔(自2.0.5版本開始)
• OpenAPI:導出當前邏輯分組下的原始OpenAPI的規(guī)范json結構(自2.0.6版本開始)
• PDF:未實現(xiàn)

5.過濾請求參數

通常我們在開發(fā)接口時,比如一個新增接口和一個修改接口，修改接口需要傳遞主鍵id、而新增接口則不需要傳遞此屬性，但大部分情況,我們只寫一個Model類,此時在新增接口時顯示主鍵id會顯得很多余。使用自定義增強注解@ApiOperationSupport中的ignoreParameters屬性，可以強制忽略要顯示的參數

5.1 忽略表單參數

我們給User實體新增一個id屬性

然后新增一個新增用戶的接口方法，用表單方式接收參數，但是忽略掉id。在@ApiOperationSupport中的ignoreParameters屬性中填寫忽略的屬性名稱即可

@PostMapping("addUser")
@ApiOperation("添加用戶")
@ApiOperationSupport(ignoreParameters = "id") // 忽略掉User中的id屬性，不顯示在文檔中
public void addUser(User user) {
}

注意：

• ignoreParameters支持以數組形式添加多個忽略參數
• ignoreParameters支持忽略級聯(lián)對象的參數，比如User實體類中有個Address類型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "addr.id"即可
• 如果要忽略的參數過多，可以使用includeParameters反向配置

5.2 忽略json參數

如果是以@RequestBody形式接收參數，那么ignoreParameters中填寫參數名.要忽略的屬性名即可

@PostMapping("addUser2")
@ApiOperation("添加用戶2")
@ApiOperationSupport(ignoreParameters = {"user.id", "user.age"})
public void addUser2(@RequestBody User user) {
}

注意

• ignoreParameters支持以數組形式添加多個忽略參數
• ignoreParameters支持忽略級聯(lián)對象的參數，比如User實體類中有個Address類型的屬性addr，那么如果想要忽略Address的屬性id，那么只需要配置為ignoreParameters = "user.addr.id"即可
• 如果要忽略的參數過多，可以使用includeParameters反向配置

6.AfterScript

AfterScript功能是Knife4j自2.0.6版本開始新增的一項特性功能，在每個接口進行調試Tab中,開發(fā)者可以根據Knife4j提供的全局變量,在接口調用之前編寫一段JavaScript腳本,當接口調用成功后,Knife4j會執(zhí)行該腳本

主要應用場景：針對JWT類型的接口，調用登錄接口后，每個接口請求時帶上Token參數，此時可以通過該腳本動態(tài)賦值全局token參數，省去復制粘貼的麻煩

Knife4j目前主要提供ke(Knife4j Environment)對象來獲取或者操作全局對象,主要包含的對象：

• global:全局操作,可以獲取或者設置目前的全局參數
• setHeader(name,value):設置當前邏輯分組下的全局參數Header請求頭
• setAllHeader(name,value):設置所有邏輯分組下的全局參數Header請求頭
• setParameter(name,value):設置當前邏輯分組下，主要是針對query類型參數進行設置全局設置。
• setAllParameter(name,value):設置所有邏輯分組下的全局參數，主要是query類型
• response:當前請求接口響應內容
• headers:服務端響應Header對象,注意,此處所有的header的名稱全部進行小寫轉換
• data:服務端響應數據(json/xml/text等等)

我們新增一個登錄接口，返回token參數

@PostMapping("login")
@ApiOperation("登錄")
public Map<String, Object> login() {
    Map<String, Object> result = new HashMap<>(2);
    result.put("success", true);
    result.put("token", "1364564646");
    return result;
}

然后在knife4j文檔中針對這個登錄接口編寫AfterScript，取出返回的token，設置到每一個請求的請求頭中

var success=ke.response.data.success;
if(success===true){
    // 獲取token
    var token=ke.response.data.token;
    // 設置當前邏輯分組下的全局Header
    ke.global.setHeader("Authorization", "Bearer " + token);
}

這樣的效果是，請求login接口成功返回token后，后續(xù)調試其他所有接口時會自動給請求頭中添加token參數，無需手動添加

7.全局參數

Knife4j提供基于UI臨時設置全局參數功能,例如后臺全局token參數等.提供該功能主要是方便開發(fā)者進行調試

目前全局參數功能主要提供兩種參數類型：query(表單)、header(請求頭)

如果后端Swagger有配置全局參數，該功能可以無視

微服務文檔聚合

在微服務架構下，如果給每個微服務都配置文檔，那么每個微服務的接口文檔都有自己獨立的訪問地址，這樣要一個個打開每個微服務的文檔非常麻煩。一般我們會采用聚合的辦法，將所有微服務的接口整合到一個文檔中

傳統(tǒng)的整合方法需要在gateway中進行大量配置，十分繁瑣。自2.0.8版本開始，Knife4j 提供了knife4j-aggregation-spring-boot-starter組件，該組件是一個基于Spring Boot系統(tǒng)的starter，他提供了以下幾種能力：

• 最輕量級、最簡單、最方便的聚合OpenApi規(guī)范的中間件
• 讓所有的基于Spring Boot的Web體系擁有了輕松聚合OpenApi的能力
• 提供4種模式供開發(fā)者選擇
• 基于本地靜態(tài)JSON文件的方式聚合OpenAPI
• 基于云端HTTP接口的方式聚合
• 基于Eureka注冊中心的方式聚合
• 基于Nacos注冊中心的方式聚合
• 基于該starter發(fā)布了Docker鏡像，跨平臺與語言讓開發(fā)者基于此Docker鏡像輕松進行聚合OpenAPI規(guī)范
• 完美兼容所有Spring Boot版本，沒有兼容性問題
• 開發(fā)者可以徹底放棄基于Zuul、Spring Cloud Gateway等復雜的聚合方式
• 兼容OpenAPI2規(guī)范以及OpenAPI3規(guī)范

目前Knife4jAggregation主要提供了四種方式進行OpenAPI文檔的聚合，主要包括：

基于OpenAPI的靜態(tài)JSON文件方式，Disk模式
基于HTTP接口的方式獲取OpenAPI，Cloud模式
基于Eureka注冊中心獲取OpenAPI，Eureka模式
基于Nacos注冊中心獲取OpenAPI，Nacos模式

Disk、Cloud、Eureka、Nacos這四種模式只能使用其中1種，不能混合一起使用(即只能配置這4中模式中的一種屬性，然后將其enable屬性設置為true,其他三種的enable則必須設置為false)

利用knife4j進行文檔聚合的步驟非常簡單：

1.創(chuàng)建一個SpringBoot項目，用于聚合文檔，引入下列依賴

 <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

2.配置需要聚合的文檔的地址

3.訪問該聚合文檔的地址，即可訪問到被聚合的所有接口文檔

1.Cloud模式

cloud模式原理是，在聚合文檔工程配置每個微服務的http接口資源地址，這樣聚合文檔工程啟動的時候可以訪問到每個微服務的http接口文檔資源地址，從而聚合每個微服務的接口文檔

這種方式可以用在沒有注冊中心，每個SpringBoot微服務單獨啟動的場景由于聚合文檔工程需要能訪問到每個微服務的http接口文檔資源地址才能做聚合，所以在聚合文檔工程啟動之前要先啟動需要被聚合的每個微服務，并且每個微服務自己要做好swagger文檔的相關配置

為了測試聚合文檔，我們首先復制出一個SpringBoot工程knife4j-app2作為第2個微服務，其主要配置與knife4j-app1一樣，只是部分地方作了名稱修改。然后再創(chuàng)建一個聚合文檔工程knife4j-agg-doc：

在聚合文檔工程knife4j-agg-doc中引入依賴

 <dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-aggregation-spring-boot-starter</artifactId>
    <version>2.0.9</version>
</dependency>

cloud模式中，yaml的配置示例如下：

knife4j:
  enableAggregation: true
  cloud:
    enable: true
    routes:
      - name: 用戶體系
        uri: 192.168.0.152:8999
        location: /v2/api-docs?group=2.X版本
        swaggerVersion: 2.0
        servicePath: /abbb/ffe
        routeAuth:
          enable: true
          username: test3
          password: 66666
    routeAuth:
      enable: true
      username: test
      password: 12313

• knife4j.cloud.enable:將該屬性設置為true，則代表啟用Cloud模式
• knife4j.cloud.routeAuth:該屬性是一個公共Basic驗證屬性(可選)，如果開發(fā)者提供的OpenAPI規(guī)范的HTTP接口需要以Basic驗證進行鑒權訪問，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節(jié)點接口都會以Basic驗證信息訪問接口
• knife4j.cloud.routeAuth.enable:是否啟用Basic驗證
• knife4j.cloud.routeAuth.usernae:Basic用戶名
• knife4j.cloud.routeAuth.password:Basic密碼
• knife4j.cloud.routes:需要聚合的服務集合(必選)，可以配置多個
• knife4j.cloud.routes.name:服務名稱(顯示名稱，最終在Ui的左上角下拉框進行顯示)
• knife4j.cloud.routes.uri:該服務的接口URI資源，如果是HTTPS，則需要完整配置
• knife4j.cloud.routes.location::具體資源接口地址，最終Knife4j是通過uri+location的組合路徑進行訪問
• knife4j.cloud.routes.swaggerVersion:版本號，默認是2.0，可選配置
• knife4j.cloud.routes.servicePath:該屬性是最終在Ui中展示的接口前綴屬性，提供該屬性的目的也是因為通常開發(fā)者在以Gateway等方式聚合時，需要一個前綴路徑來進行轉發(fā)，而最終這個前綴路徑會在每個接口中進行追加
• knife4j.cloud.routes.routeAuth:如果該Route節(jié)點的接口開啟了Basic，并且和公共配置的Basic不一樣，需要單獨配置
• knife4j.cloud.routes.routeAuth.enable:是否啟用Basic驗證
• knife4j.cloud.routes.routeAuth.usernae:Basic用戶名
• knife4j.cloud.routes.routeAuth.password:Basic密碼

我們在knife4j-agg-doc的yaml中做如下配置

server:
  port: 8010

knife4j:
  enableAggregation: true  # 開啟聚合
  cloud:
    enable: true  # 開啟cloud模式
    routes: 
      - name: 應用1    # 微服務在聚合文檔中的名稱
        uri: localhost:8000  # 微服務的http地址
        location: /v2/api-docs # 微服務文檔資源路徑
        servicePath: /api/app1 # 給每個接口添加路徑前綴，作用是拼接出經過nginx和gateway處理前的實際接口url
      - name: 應用2
        uri: localhost:8001
        location: /v2/api-docs?group=default
        servicePath: /api/app2

然后先啟動knife4j-app1與knife4j-app2，再啟動knife4j-agg-doc，訪問knife4j-agg-doc的地址http://localhost:8010/doc.html即可看到聚合后的文檔

• 可以發(fā)現(xiàn)，不同的微服務是以不同分組的形式出現(xiàn)在聚合文檔中，所以實際上配置文檔聚合是聚合某個微服務中的某個分組
• 在配置routes.location的時候，可以指定分組參數group，默認不指定代表group=default。這也意味著，我們不止可以細化到每個微服務，還可以細化到一個微服務的不同分組。如果每個微服務的swagger文檔中配置了多個分組，可以聚合每一個分組，這樣聚合文檔中可以區(qū)分選擇某一個微服務下具體分組的文檔
• 實際開發(fā)中一般情況下不建議在一個微服務中再進行分組，否則不好管理。每個微服務都用默認分組，直接以微服務為單位聚合文檔即可清晰區(qū)分開每個微服務的接口

2.Nacos模式

Nacos模式原理是，在聚合文檔工程配置每個微服務的Nacos注冊中心地址和服務名稱，這樣聚合文檔工程啟動的時候可以從Nacos訪問到每個微服務的http接口文檔資源地址，從而聚合每個微服務的接口文檔

• 這種方式適合以Nacos作為微服務注冊中心的場景
• 由于聚合文檔工程需要能訪問到Nacos獲取每個微服務的信息才能做聚合，所以在聚合文檔工程啟動之前要先啟動Nacos和需要被聚合的每個微服務，并且每個微服務要成功注冊到Nacos中
• 每個微服務自己要做好swagger文檔的相關配置

為了測試Nacos模式，首先在每個微服務中引入nacos相關依賴和配置，并啟動Nacos和微服務，將它們注冊到Nacos中

Nacos模式的可選配置如下

knife4j:
  enableAggregation: true
  nacos:
    enable: true
    serviceUrl: http://192.168.0.112:8804/nacos/
    routeAuth:
      enable: true
      username: test
      password: 12313
    routes:
      - name: 訂單服務
        serviceName: service-order
        groupName: test
        namespaceId: test
        clusters: test
        location: /v2/api-docs?group=default
        swaggerVersion: 2.0
        servicePath: /order
        routeAuth:
          enable: true
          username: test
          password: 12313

• knife4j.nacos.enable:將該屬性設置為true，則代表啟用nacos模式
• knife4j.nacos.serviceUrl:nacos注冊中心的地址
• knife4j.nacos.routeAuth:該屬性是一個公共Basic驗證屬性(可選)，如果開發(fā)者提供的OpenAPI規(guī)范的服務需要以Basic驗證進行鑒權訪問，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節(jié)點接口都會以Basic驗證信息訪問接口
• knife4j.nacos.routeAuth.enable:是否啟用Basic驗證
• knife4j.nacos.routeAuth.usernae:Basic用戶名
• knife4j.nacos.routeAuth.password:Basic密碼
• knife4j.nacos.routes:需要聚合的服務集合(必選)，可以配置多個
• knife4j.nacos.routes.name:服務名稱(顯示名稱，最終在Ui的左上角下拉框進行顯示)，如果該屬性不配置，最終Ui會顯示serviceName
• knife4j.nacos.routes.serviceName:nacos注冊中心的服務名稱
• knife4j.nacos.routes.groupName:Nacos分組名稱,非必須,開發(fā)者根據自己的實際情況進行配置
• knife4j.nacos.routes.namespaceId:命名空間id,非必須,開發(fā)者根據自己的實際情況進行配置
• knife4j.nacos.routes.clusters:集群名稱,多個集群用逗號分隔,非必須,開發(fā)者根據自己的實際情況進行配置
• knife4j.nacos.routes.uri:該服務的接口URI資源，如果是HTTPS，則需要完整配置
• knife4j.nacos.routes.location::具體資源接口地址，最終Knife4j是通過注冊服務uri+location的組合路徑進行訪問
• knife4j.nacos.routes.swaggerVersion:版本號，默認是2.0，可選配置
• knife4j.nacos.routes.servicePath:該屬性是最終在Ui中展示的接口前綴屬性，提供該屬性的目的也是因為通常開發(fā)者在以Gateway等方式聚合時，需要一個前綴路徑來進行轉發(fā)，而最終這個前綴路徑會在每個接口中進行追加
• knife4j.nacos.routes.routeAuth:如果該Route節(jié)點的接口開啟了Basic，并且和公共配置的Basic不一樣，需要單獨配置
• knife4j.nacos.routes.routeAuth.enable:是否啟用Basic驗證
• knife4j.nacos.routes.routeAuth.usernae:Basic用戶名
• knife4j.nacos.routes.routeAuth.password:Basic密碼

我們在聚合文檔工程knife4j-agg-doc的yaml中做如下配置

server:
  port: 8010

knife4j:
  enableAggregation: true
  nacos:
    enable: true  # 開啟Nacos模式
    serviceUrl: http://localhost:8848/nacos # Nacos注冊中心地址
    routes:
      - name: 應用1  # 微服務在聚合文檔中的名稱
        serviceName: APP1  # 微服務在Nacos注冊中心的名稱
        location: /v2/api-docs # 微服務文檔資源路徑
        servicePath: /api/app1 # 給每個接口添加路徑前綴，作用是拼接出經過nginx和gateway處理前的實際接口url
      - name: 應用2
        serviceName: APP2
        location: /v2/api-docs
        servicePath: /api/app2

啟動聚合文檔工程，訪問http://localhost:8010/doc.html查看聚合文檔

到此這篇關于swagger文檔增強工具knife4j使用詳解的文章就介紹到這了,更多相關swagger文檔增強工具knife4j內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

最新評論