Springboot引入Knife4j接口文档

springboot引入Knife4j接口文档

前言：前后端联调时使用knife4j文档能大大减少沟通成本，为前端测试接口连通性以及接口参数带来很大的方便。

本文档在jdk11，springboot 2.7.17版本下编写

1. 引入依赖

<!--添加Knife4j依赖-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-openapi2-spring-boot-starter</artifactId>
    <version>4.1.0</version>
</dependency>

2. 编写配置类

package com.jankin.applet.system.config;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfig {//对于配置类要求可以看懂即可，不用反复去写，将来可以CV
    //配置Swagger2的Docket的Bean实例
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // apiInfo()：配置 API 的一些基本信息，比如：文档标题title，文档描述description，文档版本号version
                .apiInfo(apiInfo())
                // select()：生成 API 文档的选择器，用于指定要生成哪些 API 文档
                .select()
                // apis()：指定要生成哪个包下的 API 文档
                .apis(RequestHandlerSelectors.basePackage("com.jankin.applet.controller"))
                // paths()：指定要生成哪个 URL 匹配模式下的 API 文档。这里使用 PathSelectors.any()，表示生成所有的 API 文档。
                .paths(PathSelectors.any())
                .build();
    }
    //文档信息配置
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("Knife4j接口文档")
                // 文档描述信息
                .description("Knife4j接口文档")
                // 文档版本号
                .version("1.0")
                .build();
    }
}

3. 测试连接

访问url ip:port/doc.html 即可访问接口文档页面

4. 注解使用

• @Api(tags = "01.用户管理模块")

  @Api标注在Controller类上，在页面上接口文档页面上会分类替代Controller名称

• @ApiOperation(value="查询列表")

  @ApiOperation标注在Controller方法上，在接口文档页面会显示value内容替代方法名

• @ApiModelProperty(value = "用户名", required = true, example = "赵丽颖")

  @ApiModelProperty标注在入参的dto变量上，value会替代具体参数名称，required会显示是否必填项，example会给出默认值

• @ApiImplicitParam(name = "id", value = "微博", required=true, dataType = "int")

  @ApiImplicitParam标注在Controller方法上，对未封装参数进行注释，value会替代具体参数名称，required会显示是否必填项，dataType 指定参数类型

• @ApiIgnore

  @ApiIgnore标注在Controller方法的入参上，被标注的参数表示忽略该参数，不会在接口文档中显示，例如HttpRequest参数不需要显示。

5. 配置移除接口文档

在生产环境肯定不允许接口文档的出现，如果每次打包生产时都移除依赖删除配置文件太麻烦，Knife4j提供配置方式，在配置文件application.yml中添加配置

knife4j:
  enable: true
  production: true

此时在打包时，配置以上配置即可不显示接口文档。

当然如果配置文件分dev和pro版本，则直接在pro中配置即可。