Springboot中整合knife4j接口文档

在项目开发过程中，web项目的前后端分离开发，APP开发，需要由前端后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发。

什么是knife4j

简单说knife4j就 swagger 的升级版API文档的一个框架,但是用起来比swagger方便多了，UI更加丰富。

界面欣赏

主页

接口文档

调试界面

参数实体

整合 knife4j

引入 maven 依赖

    com.github.xiaoymin
    knife4j-spring-boot-starter
    
    3.0.3

knife4j 配置文件

创建 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: [email protected]
 * 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项目 后台服务API接口文档")
                .description("使用 knife4j 搭建的后台服务API接口文档")
                .termsOfServiceUrl("http://localhost:8080/")
                .contact("didiplus")
                .version("1.0.0")
                .build();
    }
}

配置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: [email protected]
* CreateTime: 2022/4/25
* Desc: 数据字典控制器
*/
@RestController
@Api(tags = "数据字典")
@RequestMapping("/api/sys/dictType")
public class SysDictTypeController {
    
    @ApiOperation("添加")
    @PostMapping("/add")
    public SysDictType add() {
        SysDictType dictType = new SysDictType();
        dictType.setId("1");
        dictType.setTypeName("用户状态");
        dictType.setTypeCode("user_type");
        dictType.setDescription("用户状态");
        dictType.setEnable("true");
        return  dictType;
    }
    
}

通过 @Api 注解标注需要生成接口文档，通过 @ApiOperation 注解标注接口名。 同时我们给 SysDictType 也加上对应的注解

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: [email protected]
 * CreateTime: 2022/4/25
 * Desc: 字典类型领域模型
 */

@Data
@ApiModel(value = "字典类型")
public class SysDictType {

    @ApiModelProperty("ID")
    private String id;

    @NotEmpty(message = "字典编码不能为空")
    @ApiModelProperty(name = "字典名称",example = "用户ID")
    private String typeName;

    @NotEmpty(message = "字典编码不能为空")
    @ApiModelProperty(value = "字典编码")
    private String typeCode;

    @ApiModelProperty(value = "字典描述")
    private String description;

    @NotEmpty(message = "字典状态不能为空")
    @ApiModelProperty(value = "字典状态")
    private String enable;
}

通过 @ApiModel 标注这是一个参数实体，通过 @ApiModelProperty 标注字段说明。

访问 http://localhost:8080/doc.html体验一下,出现访问资源异常

出现这个问题的原因是因为我们加上了 ResponseBodyAdvice 统一处理返回值/响应体，导致给Swagger的返回值也包装了一层，UI页面无法解析。可以通过 http://localhost:8080/v2/api-docs?group=SwaggerDemo 观察Swagger返回的json数据。

既然知道了问题原因那就很好解决了，我们只需要在 ResponseBodyAdvice 处理类中只转换我们自己项目的接口即可。

@RestControllerAdvice(basePackages = "com.didiplus.modules")
public class ResponseAdvice  implements ResponseBodyAdvice