springboot2+swagger3集成笔记

前言

swagger用起来还是很爽的 直接内嵌代码中 前端老师也能看到最新的文档 也能直接测试访问 减少撕b的机会
spring boot1.x 集成swagger2.x 就不用说了
spring boot2.x 由于多了个 webflux swagger在3.x的时候 也做出适配
分别为使用webflux 和传统servlet 模式提供适配

实例

maven配置

        <!--由于 swagger3 还未放到maven 中央仓库 只能添加私服来获取jar-->
        <repository>
            <id>jcenter-snapshots</id>
            <name>jcenter</name>
            <url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
            <releases>
                <enabled>true</enabled>
            </releases>
        </repository>
        ...
                <!--swagger version -->
                <swagger.version>3.0.0-SNAPSHOT</swagger.version>
        ...        
        
             <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger2</artifactId>
                    <version>${swagger.version}</version>
                </dependency>
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-spring-webflux</artifactId>
                    <version>${swagger.version}</version>
                </dependency>
<!--            如果是使用servlet容器 需要将webflux替换为webmvc 配合注解 @EnableSwagger2WebMvc-->
<!--        <dependency>-->
<!--            <groupId>io.springfox</groupId>-->
<!--            <artifactId>springfox-spring-webmvc</artifactId>-->
<!--            <version>${swagger.version}</version>-->
<!--        </dependency>-->
                <dependency>
                    <groupId>io.springfox</groupId>
                    <artifactId>springfox-swagger-ui</artifactId>
                    <version>${swagger.version}</version>
                </dependency>
        

• 2020-07-22 更新使用springfox.boot.starter来接入swagger
  swagger其他参数不变 依赖改为

  版本参考maven中央仓库版本即可: https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter

<springfox.boot.version>3.0.0</springfox.boot.version>
....
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>${springfox.boot.version}</version>
    </dependency>

swagger配置

swagger2.x中启动swagger是使用 @EnableSwagger2注解
在swagger3.x中拆分为 @EnableSwagger2WebMvc(传统servlet模式) @EnableSwagger2WebFlux(webflux模式) 分别适配不同模式

package com.ming.base.config;

import com.ming.Start;
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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebFlux;

/**
 * swagger config
 *
 * @author ming
 * @date 2019-09-04 14:12:49
 */
@Configuration
@EnableSwagger2WebFlux
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(new ApiInfoBuilder()
                .description("ming 工作台api")
                .title("ming-workbench")
                .version("1.0.0")
                .build()
        )
                .select()
                .apis(RequestHandlerSelectors.basePackage(Start.class.getPackageName()))
                .paths(PathSelectors.any())
                .build()
                ;
    }
}

访问

由于引入的有 swagger-ui模块 如果spring boot2.x 没有特殊的修改 直接访问/swagger-ui.html即可

http://host:port/swagger-ui.html

异常处理

接口、swagger-ui.html 404

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    //注册 swagger 相关页面
    registry.addResourceHandler("/swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
}

出现提示框

一般是获取相关接口数据异常 主要看看 是不是被拦截、或者被修改了

• 接口被拦截器处理

  @Override
  public void addInterceptors(InterceptorRegistry registry) {
      registry.addInterceptor("拦截器").excludePathPatterns("classpath*:/static/**")
              // swagger 排除规则
              .excludePathPatterns("/swagger-ui.html")
              .excludePathPatterns("/swagger-resources/**")
              .excludePathPatterns("/error")
              .excludePathPatterns("/webjars/**");;
  }

• 接口被过滤器处理

  //如果是排除列表的 uri 前缀 不进行任何操作 只增强
  for (String s : 排除uri列表) {
      if (uri.matches(s)) {
          chain.doFilter(result, response);
          return;
      }
  }

• 存在全局的返回值处理
  例如 spring 的controllerAdvice
  跟过滤器类似 直接处理即可

  //如果是排除列表的 uri 前缀 不进行任何操作 只增强
  for (String s : 排除uri列表) {
      if (uri.matches(s)) {
          chain.doFilter(result, response);
          return;
      }
  }

无法启动

• spring plugin core版本异常
  提示如下:

  2020-06-03 14:01:46.323  INFO 35910 --- [  restartedMain] ConditionEvaluationReportLoggingListener : 
  
  Error starting ApplicationContext. To display the conditions report re-run your application with 'debug' enabled.
  2020-06-03 14:01:46.328 ERROR 35910 --- [  restartedMain] o.s.b.d.LoggingFailureAnalysisReporter   : 
  
  ***************************
  APPLICATION FAILED TO START
  ***************************
  
  Description:
  
  An attempt was made to call a method that does not exist. The attempt was made from the following location:
  
      springfox.documentation.spring.web.plugins.DocumentationPluginsManager.createContextBuilder(DocumentationPluginsManager.java:154)
  
  The following method did not exist:
  
      'org.springframework.plugin.core.Plugin org.springframework.plugin.core.PluginRegistry.getPluginOrDefaultFor(java.lang.Object, org.springframework.plugin.core.Plugin)'
  
  The method's class, org.springframework.plugin.core.PluginRegistry, is available from the following locations:
  
      jar:file:/home/ming/.m2/repository/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar!/org/springframework/plugin/core/PluginRegistry.class
  
  It was loaded from the following location:
  
      file:/home/ming/.m2/repository/org/springframework/plugin/spring-plugin-core/1.2.0.RELEASE/spring-plugin-core-1.2.0.RELEASE.jar
  
  
  Action:
  
  Correct the classpath of your application so that it contains a single, compatible version of org.springframework.plugin.core.PluginRegistry

  解决办法:
  根据提升调整 spring plugin core版本

  <dependency>
      <groupId>org.springframework.plugin</groupId>
      <artifactId>spring-plugin-core</artifactId>
      <version>2.0.0.RELEASE</version>
  </dependency>

总结

spring 在进步 swagger 也没有落下
swagger 在小项目中 非常方便 文档会跟着代码走 减小前后端沟通的成本