springboot集成knife4j

官方文档
文章内容根据官方文档进行配置撰写的，详细信息请直接查看官方文档。
使用Knife4j2.0.6及以上的版本，Spring Boot的版本必须大于等于2.2.x

1.配置

1.pom

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

2.java配置

import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.EnableSwagger2;

/**
 * swagger配置
 * <http://host>:port/doc.html
 */
@Configuration
@EnableSwagger2
@EnableKnife4j
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfig {
    @Value("${swagger.module.name}")
    private String swaggerModuleName;

    @Bean
    public BCryptPasswordEncoder getEncoder() {
        return new BCryptPasswordEncoder();
    }
    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
        Docket docket = new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //分组名称
//                .groupName("v1.0")
                .select()
                //这里指定Controller扫描包路径
                .apis(RequestHandlerSelectors.basePackage("com.test.*.controller"))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Knife4j构建RESTful APIs")
                .description(swaggerModuleName)
                .termsOfServiceUrl("<https://doc.xiaominfo.com/>")
                .version("1.0").build();
    }

}

3.application

knife4j:
  # 开启生产环境屏蔽
  production: true
# 增强功能需要通过配置yml配置文件开启增强,自2.0.7开始
  enable: true
# 开启Swagger的Basic认证功能,默认是false
  basic:
      enable: true
      # Basic认证用户名
      username: test
      # Basic认证密码
      password: 123
swagger:
  module:
    name: testModel
# 关闭烦人的提示信息，如果你喜欢，你可以不用如下配置
logging:
  level:
    springfox:
      documentation:
        spring:
          web:
            readers:
              operation:
                CachingOperationNameGenerator: warn

3.问题与注意点

3.1 架包冲突问题

• Handler dispatch failed; nested exception is java.lang.NoSuchMethodError: io.swagger.models.Swagger.setVendorExtensions(Ljava/util/Map;)V
  • 原因是因为 swagger.models的jar包冲突了，在pom将其排除即可。

3.2 日志类问题

• 启动的时候打印一连串的日志提示信息：Generating unique operation named

  • 这是因为spring 在加载controller 的时候，发现这些类里面的方法名称有重复的，所以给你自动生成了一些名称，用以区分这些方法

  • 解决方法:

    1. 通过修改日志等级来关闭提示，在application.properties或者application.yml中配置该类的日志等级。

       • properties格式：logging.level.springfox.documentation.spring.web.readers.operation.CachingOperationNameGenerator=warn
       • yml格式：

       logging:
         level:
           springfox:
             documentation:
               spring:
                 web:
                   readers:
                     operation:
                       CachingOperationNameGenerator: warn
       

    2. 通过aop切面切入的方法，不进行日志的打印，或者以警告的方式进行日志打印，比较麻烦，具体的可以看参考地址

  • 参考地址：Springboot 启动信息：Generating unique operation named