springboot集成knife4j

你的名字 2022-10-15 14:51 32阅读 0赞

> [官方文档][Link 1]  
> 文章内容根据官方文档进行配置撰写的，详细信息请直接查看官方文档。  
> 使用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][Springboot _Generating unique operation named]

[Link 1]: https://doc.xiaominfo.com/
[Springboot _Generating unique operation named]: https://www.codeleading.com/article/62262541279/