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

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

基本使用

想要使用knife4j非常簡(jiǎn)單，只要在Springboot項(xiàng)目中引入knife4j的依賴即可

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

注意：引入knife4j后會(huì)自動(dòng)引入swagger相關(guān)依賴

所以無(wú)需再手動(dòng)引入swagger相關(guān)依賴，否則會(huì)引起版本沖突，在使用knife4j的一些增強(qiáng)功能時(shí)會(huì)報(bào)錯(cuò)

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

// Controller1
@RestController
@RequestMapping("controller1")
@Api(tags = "應(yīng)用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 = "應(yīng)用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) {

    }
}

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

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

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

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

此時(shí)啟動(dòng)項(xiàng)目，訪問(wèn)ip:端口/doc.html即可看到knife4j的文檔界面

增強(qiáng)功能

使用knife4j增強(qiáng)功能的前提是要在yaml配置中開(kāi)啟增強(qiáng)模式

knife4j:
  enable: true

1.添加接口作者

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

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

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

2.生產(chǎn)環(huán)境關(guān)閉文檔

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

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

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

此時(shí)只要以prod環(huán)境運(yùn)行，就無(wú)法訪問(wèn)到接口文檔

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

3.接口排序

接口排序的方式有2種：

針對(duì)不同Controller排序：Controller上標(biāo)注@ApiSupport(order = 序號(hào))

針對(duì)同一個(gè)Controller中的不同方法排序：同一個(gè)Controller不同接口方法上標(biāo)注@ApiOperationSupport(order = 序號(hào))

4.導(dǎo)出離線文檔

• markdown：導(dǎo)出當(dāng)前邏輯分組下所有接口的Markdown格式的文檔
• Html：導(dǎo)出當(dāng)前邏輯分組下所有接口的Html格式的文檔
• Word:導(dǎo)出當(dāng)前邏輯分組下所有接口的Word格式的文檔(自2.0.5版本開(kāi)始)
• OpenAPI:導(dǎo)出當(dāng)前邏輯分組下的原始OpenAPI的規(guī)范json結(jié)構(gòu)(自2.0.6版本開(kāi)始)
• PDF:未實(shí)現(xiàn)

5.過(guò)濾請(qǐng)求參數(shù)

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

5.1 忽略表單參數(shù)

我們給User實(shí)體新增一個(gè)id屬性

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

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

注意：

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

5.2 忽略json參數(shù)

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

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

注意

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

6.AfterScript

AfterScript功能是Knife4j自2.0.6版本開(kāi)始新增的一項(xiàng)特性功能，在每個(gè)接口進(jìn)行調(diào)試Tab中,開(kāi)發(fā)者可以根據(jù)Knife4j提供的全局變量,在接口調(diào)用之前編寫(xiě)一段JavaScript腳本,當(dāng)接口調(diào)用成功后,Knife4j會(huì)執(zhí)行該腳本

主要應(yīng)用場(chǎng)景：針對(duì)JWT類型的接口，調(diào)用登錄接口后，每個(gè)接口請(qǐng)求時(shí)帶上Token參數(shù)，此時(shí)可以通過(guò)該腳本動(dòng)態(tài)賦值全局token參數(shù)，省去復(fù)制粘貼的麻煩

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

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

我們新增一個(gè)登錄接口，返回token參數(shù)

@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文檔中針對(duì)這個(gè)登錄接口編寫(xiě)AfterScript，取出返回的token，設(shè)置到每一個(gè)請(qǐng)求的請(qǐng)求頭中

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

這樣的效果是，請(qǐng)求login接口成功返回token后，后續(xù)調(diào)試其他所有接口時(shí)會(huì)自動(dòng)給請(qǐng)求頭中添加token參數(shù)，無(wú)需手動(dòng)添加

7.全局參數(shù)

Knife4j提供基于UI臨時(shí)設(shè)置全局參數(shù)功能,例如后臺(tái)全局token參數(shù)等.提供該功能主要是方便開(kāi)發(fā)者進(jìn)行調(diào)試

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

如果后端Swagger有配置全局參數(shù)，該功能可以無(wú)視

微服務(wù)文檔聚合

在微服務(wù)架構(gòu)下，如果給每個(gè)微服務(wù)都配置文檔，那么每個(gè)微服務(wù)的接口文檔都有自己獨(dú)立的訪問(wèn)地址，這樣要一個(gè)個(gè)打開(kāi)每個(gè)微服務(wù)的文檔非常麻煩。一般我們會(huì)采用聚合的辦法，將所有微服務(wù)的接口整合到一個(gè)文檔中

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

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

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

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

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

利用knife4j進(jìn)行文檔聚合的步驟非常簡(jiǎn)單：

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

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

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

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

1.Cloud模式

cloud模式原理是，在聚合文檔工程配置每個(gè)微服務(wù)的http接口資源地址，這樣聚合文檔工程啟動(dòng)的時(shí)候可以訪問(wèn)到每個(gè)微服務(wù)的http接口文檔資源地址，從而聚合每個(gè)微服務(wù)的接口文檔

這種方式可以用在沒(méi)有注冊(cè)中心，每個(gè)SpringBoot微服務(wù)單獨(dú)啟動(dòng)的場(chǎng)景由于聚合文檔工程需要能訪問(wèn)到每個(gè)微服務(wù)的http接口文檔資源地址才能做聚合，所以在聚合文檔工程啟動(dòng)之前要先啟動(dòng)需要被聚合的每個(gè)微服務(wù)，并且每個(gè)微服務(wù)自己要做好swagger文檔的相關(guān)配置

為了測(cè)試聚合文檔，我們首先復(fù)制出一個(gè)SpringBoot工程knife4j-app2作為第2個(gè)微服務(wù)，其主要配置與knife4j-app1一樣，只是部分地方作了名稱修改。然后再創(chuàng)建一個(gè)聚合文檔工程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:將該屬性設(shè)置為true，則代表啟用Cloud模式
• knife4j.cloud.routeAuth:該屬性是一個(gè)公共Basic驗(yàn)證屬性(可選)，如果開(kāi)發(fā)者提供的OpenAPI規(guī)范的HTTP接口需要以Basic驗(yàn)證進(jìn)行鑒權(quán)訪問(wèn)，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節(jié)點(diǎn)接口都會(huì)以Basic驗(yàn)證信息訪問(wèn)接口
• knife4j.cloud.routeAuth.enable:是否啟用Basic驗(yàn)證
• knife4j.cloud.routeAuth.usernae:Basic用戶名
• knife4j.cloud.routeAuth.password:Basic密碼
• knife4j.cloud.routes:需要聚合的服務(wù)集合(必選)，可以配置多個(gè)
• knife4j.cloud.routes.name:服務(wù)名稱(顯示名稱，最終在Ui的左上角下拉框進(jìn)行顯示)
• knife4j.cloud.routes.uri:該服務(wù)的接口URI資源，如果是HTTPS，則需要完整配置
• knife4j.cloud.routes.location::具體資源接口地址，最終Knife4j是通過(guò)uri+location的組合路徑進(jìn)行訪問(wèn)
• knife4j.cloud.routes.swaggerVersion:版本號(hào)，默認(rèn)是2.0，可選配置
• knife4j.cloud.routes.servicePath:該屬性是最終在Ui中展示的接口前綴屬性，提供該屬性的目的也是因?yàn)橥ǔｉ_(kāi)發(fā)者在以Gateway等方式聚合時(shí)，需要一個(gè)前綴路徑來(lái)進(jìn)行轉(zhuǎn)發(fā)，而最終這個(gè)前綴路徑會(huì)在每個(gè)接口中進(jìn)行追加
• knife4j.cloud.routes.routeAuth:如果該Route節(jié)點(diǎn)的接口開(kāi)啟了Basic，并且和公共配置的Basic不一樣，需要單獨(dú)配置
• knife4j.cloud.routes.routeAuth.enable:是否啟用Basic驗(yàn)證
• knife4j.cloud.routes.routeAuth.usernae:Basic用戶名
• knife4j.cloud.routes.routeAuth.password:Basic密碼

我們?cè)?code>knife4j-agg-doc的yaml中做如下配置

server:
  port: 8010

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

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

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

2.Nacos模式

Nacos模式原理是，在聚合文檔工程配置每個(gè)微服務(wù)的Nacos注冊(cè)中心地址和服務(wù)名稱，這樣聚合文檔工程啟動(dòng)的時(shí)候可以從Nacos訪問(wèn)到每個(gè)微服務(wù)的http接口文檔資源地址，從而聚合每個(gè)微服務(wù)的接口文檔

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

為了測(cè)試Nacos模式，首先在每個(gè)微服務(wù)中引入nacos相關(guān)依賴和配置，并啟動(dòng)Nacos和微服務(wù)，將它們注冊(cè)到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: 訂單服務(wù)
        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:將該屬性設(shè)置為true，則代表啟用nacos模式
• knife4j.nacos.serviceUrl:nacos注冊(cè)中心的地址
• knife4j.nacos.routeAuth:該屬性是一個(gè)公共Basic驗(yàn)證屬性(可選)，如果開(kāi)發(fā)者提供的OpenAPI規(guī)范的服務(wù)需要以Basic驗(yàn)證進(jìn)行鑒權(quán)訪問(wèn)，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節(jié)點(diǎn)接口都會(huì)以Basic驗(yàn)證信息訪問(wèn)接口
• knife4j.nacos.routeAuth.enable:是否啟用Basic驗(yàn)證
• knife4j.nacos.routeAuth.usernae:Basic用戶名
• knife4j.nacos.routeAuth.password:Basic密碼
• knife4j.nacos.routes:需要聚合的服務(wù)集合(必選)，可以配置多個(gè)
• knife4j.nacos.routes.name:服務(wù)名稱(顯示名稱，最終在Ui的左上角下拉框進(jìn)行顯示)，如果該屬性不配置，最終Ui會(huì)顯示serviceName
• knife4j.nacos.routes.serviceName:nacos注冊(cè)中心的服務(wù)名稱
• knife4j.nacos.routes.groupName:Nacos分組名稱,非必須,開(kāi)發(fā)者根據(jù)自己的實(shí)際情況進(jìn)行配置
• knife4j.nacos.routes.namespaceId:命名空間id,非必須,開(kāi)發(fā)者根據(jù)自己的實(shí)際情況進(jìn)行配置
• knife4j.nacos.routes.clusters:集群名稱,多個(gè)集群用逗號(hào)分隔,非必須,開(kāi)發(fā)者根據(jù)自己的實(shí)際情況進(jìn)行配置
• knife4j.nacos.routes.uri:該服務(wù)的接口URI資源，如果是HTTPS，則需要完整配置
• knife4j.nacos.routes.location::具體資源接口地址，最終Knife4j是通過(guò)注冊(cè)服務(wù)uri+location的組合路徑進(jìn)行訪問(wèn)
• knife4j.nacos.routes.swaggerVersion:版本號(hào)，默認(rèn)是2.0，可選配置
• knife4j.nacos.routes.servicePath:該屬性是最終在Ui中展示的接口前綴屬性，提供該屬性的目的也是因?yàn)橥ǔｉ_(kāi)發(fā)者在以Gateway等方式聚合時(shí)，需要一個(gè)前綴路徑來(lái)進(jìn)行轉(zhuǎn)發(fā)，而最終這個(gè)前綴路徑會(huì)在每個(gè)接口中進(jìn)行追加
• knife4j.nacos.routes.routeAuth:如果該Route節(jié)點(diǎn)的接口開(kāi)啟了Basic，并且和公共配置的Basic不一樣，需要單獨(dú)配置
• knife4j.nacos.routes.routeAuth.enable:是否啟用Basic驗(yàn)證
• knife4j.nacos.routes.routeAuth.usernae:Basic用戶名
• knife4j.nacos.routes.routeAuth.password:Basic密碼

我們?cè)诰酆衔臋n工程knife4j-agg-doc的yaml中做如下配置

server:
  port: 8010

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

啟動(dòng)聚合文檔工程，訪問(wèn)http://localhost:8010/doc.html查看聚合文檔

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

最新評(píng)論