Springboot中整合knife4j接口文檔的過程詳解

更新時(shí)間：2022年04月27日 08:46:51 作者：北根娃

knife4j就swagger的升級(jí)版API文檔的一個(gè)框架,但是用起來比swagger方便多了，UI更加豐富，這篇文章主要介紹了Springboot中整合knife4j接口文檔,需要的朋友可以參考下

什么是knife4j

簡(jiǎn)單說knife4j就swagger的升級(jí)版API文檔的一個(gè)框架,但是用起來比swagger方便多了，UI更加豐富。

界面欣賞

主頁(yè)

接口文檔

調(diào)試界面

參數(shù)實(shí)體

整合 knife4j

引入 maven 依賴

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <!--在引用時(shí)請(qǐng)?jiān)趍aven中央倉(cāng)庫(kù)搜索3.X最新版本號(hào)-->
    <version>3.0.3</version>
</dependency>

knife4j 配置文件

創(chuàng)建 Knife4jConfig 文件

package com.didiplus.common.config;

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
/**
 * Author: didiplus
 * Email: 972479352@qq.com
 * CreateTime: 2022/4/25
 * Desc: knife4j 配置
 */
@Configuration
@EnableKnife4j
public class Knife4jConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.didiplus"))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot項(xiàng)目 后臺(tái)服務(wù)API接口文檔")
                .description("使用 knife4j 搭建的后臺(tái)服務(wù)API接口文檔")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("didiplus")
                .version("1.0.0")
}

配置API接口

package com.didiplus.modules.sys.controller;
import com.didiplus.modules.sys.domain.SysDictType;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* Author: didiplus
* Email: 972479352@qq.com
* CreateTime: 2022/4/25
* Desc: 數(shù)據(jù)字典控制器
*/
@RestController
@Api(tags = "數(shù)據(jù)字典")
@RequestMapping("/api/sys/dictType")
public class SysDictTypeController {
    
    @ApiOperation("添加")
    @PostMapping("/add")
    public SysDictType add() {
        SysDictType dictType = new SysDictType();
        dictType.setId("1");
        dictType.setTypeName("用戶狀態(tài)");
        dictType.setTypeCode("user_type");
        dictType.setDescription("用戶狀態(tài)");
        dictType.setEnable("true");
        return  dictType;
    }
    
}

通過 @Api注解標(biāo)注需要生成接口文檔，通過 @ApiOperation注解標(biāo)注接口名。同時(shí)我們給 SysDictType也加上對(duì)應(yīng)的注解

package com.didiplus.modules.sys.domain;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotEmpty;
/**
 * Author: didiplus
 * Email: 972479352@qq.com
 * CreateTime: 2022/4/25
 * Desc: 字典類型領(lǐng)域模型
 */
@Data
@ApiModel(value = "字典類型")
public class SysDictType {
    @ApiModelProperty("ID")
    private String id;
    @NotEmpty(message = "字典編碼不能為空")
    @ApiModelProperty(name = "字典名稱",example = "用戶ID")
    private String typeName;
    @ApiModelProperty(value = "字典編碼")
    private String typeCode;
    @ApiModelProperty(value = "字典描述")
    private String description;
    @NotEmpty(message = "字典狀態(tài)不能為空")
    @ApiModelProperty(value = "字典狀態(tài)")
    private String enable;
}

通過 @ApiModel標(biāo)注這是一個(gè)參數(shù)實(shí)體，通過 @ApiModelProperty標(biāo)注字段說明。
訪問 http://localhost:8080/doc.html體驗(yàn)一下,出現(xiàn)訪問資源異常

出現(xiàn)這個(gè)問題的原因是因?yàn)槲覀兗由狭?code> ResponseBodyAdvice統(tǒng)一處理返回值/響應(yīng)體，導(dǎo)致給Swagger的返回值也包裝了一層，UI頁(yè)面無法解析。可以通過 http://localhost:8080/v2/api-docs?group=SwaggerDemo觀察Swagger返回的json數(shù)據(jù)。

既然知道了問題原因那就很好解決了，我們只需要在ResponseBodyAdvice處理類中只轉(zhuǎn)換我們自己項(xiàng)目的接口即可。

@RestControllerAdvice(basePackages = "com.didiplus.modules")
public class ResponseAdvice  implements ResponseBodyAdvice<Object> {
....省略....
}

詳細(xì)的可以參考SpringBoot 如何統(tǒng)一后端返回格式。通過添加basePackage屬性限定統(tǒng)一返回值的范圍，這樣就不影Swagger了，重啟服務(wù)器再次訪問swagger接口地址，就可以看到接口文檔頁(yè)面了。

knife4j 常用特性

knife4j 在 swagger 的基礎(chǔ)上做了許多增強(qiáng)，這里介紹幾個(gè)最常用的。使用增強(qiáng)特性需在application.yml 中開啟。

knife4j:
  production: false
  enable: true

全局參數(shù)

前后端分離開發(fā)中一般使用 token 作為請(qǐng)求參數(shù)進(jìn)行身份與權(quán)限鑒定，有放在 query（表單）和 header（請(qǐng)求頭）的，knife4j 對(duì)這兩種都進(jìn)行了支持，只需在側(cè)邊欄‘文檔管理 -> 全局參數(shù)設(shè)置’中設(shè)置。