Spring Boot 集成新版 Swagger2 (starter方式)

一、 了解官方最新资料

截止到 2021年04月，Springfox 的 Swagger2 依赖版本最高到 3.0.0。
但至少在 2.10.5 版本就已经有了不少变化，比如找不到 @EnableSwagger2 的注解了等等。
先到Springfox GH地址：https://github.com/springfox/springfox

看 Getting Started, 终于有 swagger 的 starter 了, Spring Boot 用户更方便集成了

可以看到主要变动：

1. Remove explicit dependencies on springfox-swagger2
2. Remove the @EnableSwagger2 annotations
3. Add the springfox-boot-starter dependency
4. Springfox 3.x removes dependencies on guava and other 3rd party libraries (not zero dep yet! depends on spring plugin and open api libraries for annotations and models) so if you used guava predicates/functions those will need to transition to java 8 function interfaces
   ...

大意为

1. 移除 springfox-swagger2 的显式依赖 (个人理解是用新的依赖不需要添加这个旧的 springfox-swagger2 依赖了)
2. 移除了 @EnableSwagger2 注解 (这是与之前版本明显区别的地方)
3. 新增了 starter 方式的依赖
4. Springfox 3.x 版本移除了 guava 和其它一些第三方库 (不过尚未完全移除), 如果使用 guava 库的断言/函数式接口功能的需要过渡到 java 8 的函数式接口
   ...

二、记录新的集成方式

1. POM

大部分内容依然没变，唯一不同的是依赖。与 Springboot 集成可用新的依赖：

        
            io.springfox
            springfox-boot-starter
            3.0.0
        

2. 配置类

SwaggerConfig.java（不需要 @EnableSwagger2 了）

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("org.example.consumer.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * Api 文档详细信息
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Title")
                .contact(new Contact("name", "url", "email"))
                .version("1.0.0")
                .description("description")
                .build();
    }
}

最简配置只需以上两步即可。

URL: http://127.0.0.1:8990/swagger-ui/index.html

(8990 是我配置的项目端口)

三、SpringBoot 2.6.x 集成的问题

SpringBoot 2.6.x 在集成时会报错:

Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException

经过深层 debug，我发现根本原因是 SpringBoot 2.6 的换了 MVC 的路径匹配策略, 由 ANT_PATH_MATCHER 换成了 PATH_PATTERN_PARSER。

解决方案:

1. 等 Swagger 适配 SpringBoot 2.6；

2. 自己改 Swagger 的代码打本地包适配；

3. 使用 2.6 之前的 SpringBoot 版本；

4. 在 application.yml 中将配置策略改回 ANT_PATH_MATCHER：

   spring:
     mvc:
       pathmatch:
         matching-strategy: ant_path_matcher