springboot集成knife4j詳細教程

使用原生的swagger作為接口文檔，功能不夠強大，并且默認的ui比較簡陋，不符合大眾審美。所以實際開發中推薦使用knife4j對swagger進行增強。knife4j的地址：https://gitee.com/xiaoym/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環境，創建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;
}

然后創建swagger配置類

@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {// 創建Docket存入容器，Docket代表一個接口文檔@Beanpublic Docket webApiConfig(){return new Docket(DocumentationType.SWAGGER_2)// 創建接口文檔的具體信息.apiInfo(webApiInfo())// 創建選擇器，控制哪些接口被加入文檔.select()// 指定@ApiOperation標注的接口被加入文檔.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).build();}// 創建接口文檔的具體信息，會顯示在接口文檔頁面中private ApiInfo webApiInfo(){return new ApiInfoBuilder()// 文檔標題.title("標題：用戶管理系統接口文檔")// 文檔描述.description("描述：本文檔描述了用戶管理系統的接口定義")// 版本.version("1.0")// 聯系人信息.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優先級更高

2.生產環境關閉文檔

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

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

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

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

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

3.接口排序
接口排序的方式有2種：

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

4.導出離線文檔

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

?5.過濾請求參數
通常我們在開發接口時,比如一個新增接口和一個修改接口，修改接口需要傳遞主鍵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支持忽略級聯對象的參數，比如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) {}

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

主要應用場景：針對JWT類型的接口，調用登錄接口后，每個接口請求時帶上Token參數，此時可以通過該腳本動態賦值全局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){// 獲取tokenvar token=ke.response.data.token;// 設置當前邏輯分組下的全局Headerke.global.setHeader("Authorization", "Bearer " + token);
}

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

7.全局參數

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

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

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

微服務文檔聚合

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

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

最輕量級、最簡單、最方便的聚合OpenApi規范的中間件
讓所有的基于Spring Boot的Web體系擁有了輕松聚合OpenApi的能力
提供4種模式供開發者選擇

基于本地靜態JSON文件的方式聚合OpenAPI
基于云端HTTP接口的方式聚合
基于Eureka注冊中心的方式聚合
基于Nacos注冊中心的方式聚合

基于該starter發布了Docker鏡像，跨平臺與語言讓開發者基于此Docker鏡像輕松進行聚合OpenAPI規范
完美兼容所有Spring Boot版本，沒有兼容性問題
開發者可以徹底放棄基于Zuul、Spring Cloud Gateway等復雜的聚合方式
兼容OpenAPI2規范以及OpenAPI3規范
目前Knife4jAggregation主要提供了四種方式進行OpenAPI文檔的聚合，主要包括：

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

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

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

1、創建一個SpringBoot項目，用于聚合文檔，引入下列依賴

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

配置需要聚合的文檔的地址
訪問該聚合文檔的地址，即可訪問到被聚合的所有接口文檔

1.Cloud模式

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

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

為了測試聚合文檔，我們首先復制出一個SpringBoot工程knife4j-app2作為第2個微服務，其主要配置與knife4j-app1一樣，只是部分地方作了名稱修改。然后再創建一個聚合文檔工程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: truecloud:enable: trueroutes:- name: 用戶體系uri: 192.168.0.152:8999location: /v2/api-docs?group=2.X版本swaggerVersion: 2.0servicePath: /abbb/fferouteAuth:enable: trueusername: test3password: 66666routeAuth:enable: trueusername: testpassword: 12313

knife4j.cloud.enable:將該屬性設置為true，則代表啟用Cloud模式
knife4j.cloud.routeAuth:該屬性是一個公共Basic驗證屬性(可選)，如果開發者提供的OpenAPI規范的HTTP接口需要以Basic驗證進行鑒權訪問，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節點接口都會以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中展示的接口前綴屬性，提供該屬性的目的也是因為通常開發者在以Gateway等方式聚合時，需要一個前綴路徑來進行轉發，而最終這個前綴路徑會在每個接口中進行追加
knife4j.cloud.routes.routeAuth:如果該Route節點的接口開啟了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: 8010knife4j:enableAggregation: true  # 開啟聚合cloud:enable: true  # 開啟cloud模式routes: - name: 應用1    # 微服務在聚合文檔中的名稱uri: localhost:8000  # 微服務的http地址location: /v2/api-docs # 微服務文檔資源路徑servicePath: /api/app1 # 給每個接口添加路徑前綴，作用是拼接出經過nginx和gateway處理前的實際接口url- name: 應用2uri: localhost:8001location: /v2/api-docs?group=defaultservicePath: /api/app2

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

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

2.Nacos模式

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

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

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

Nacos模式的可選配置如下

knife4j:enableAggregation: truenacos:enable: trueserviceUrl: http://192.168.0.112:8804/nacos/routeAuth:enable: trueusername: testpassword: 12313routes:- name: 訂單服務serviceName: service-ordergroupName: testnamespaceId: testclusters: testlocation: /v2/api-docs?group=defaultswaggerVersion: 2.0servicePath: /orderrouteAuth:enable: trueusername: testpassword: 12313

knife4j.nacos.enable:將該屬性設置為true，則代表啟用nacos模式
knife4j.nacos.serviceUrl:nacos注冊中心的地址
knife4j.nacos.routeAuth:該屬性是一個公共Basic驗證屬性(可選)，如果開發者提供的OpenAPI規范的服務需要以Basic驗證進行鑒權訪問，那么可以配置該屬性，如果配置該屬性，則該模式下所有配置的Routes節點接口都會以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分組名稱,非必須,開發者根據自己的實際情況進行配置
knife4j.nacos.routes.namespaceId:命名空間id,非必須,開發者根據自己的實際情況進行配置
knife4j.nacos.routes.clusters:集群名稱,多個集群用逗號分隔,非必須,開發者根據自己的實際情況進行配置
knife4j.nacos.routes.uri:該服務的接口URI資源，如果是HTTPS，則需要完整配置
knife4j.nacos.routes.location::具體資源接口地址，最終Knife4j是通過注冊服務uri+location的組合路徑進行訪問
knife4j.nacos.routes.swaggerVersion:版本號，默認是2.0，可選配置
knife4j.nacos.routes.servicePath:該屬性是最終在Ui中展示的接口前綴屬性，提供該屬性的目的也是因為通常開發者在以Gateway等方式聚合時，需要一個前綴路徑來進行轉發，而最終這個前綴路徑會在每個接口中進行追加
knife4j.nacos.routes.routeAuth:如果該Route節點的接口開啟了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: 8010knife4j:enableAggregation: truenacos: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: 應用2serviceName: APP2location: /v2/api-docsservicePath: /api/app2

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