Springboot集成Swagger2和Swagger3

Springboot集成Swagger2和Swagger3

github仓库地址：https://github.com/xiaoxingOvO/springboot-study

前言

Swagger3是在Swagger2上做了大版本升级，使用方式差别不大，需要注意的是部分区别和配置的不同（如下表所示）。下面分别介绍了Springboot整合Swagger2和Swagger3的过程。

区别	Swagger2	Swagger3
依赖	springfox-swagger2、springfox-swagger-ui	springfox-boot-starter
启动注解	@EnableSwagger2	@EnableOpenApi
Document类型	DocumentationType.SWAGGER_2	DocumentationType.OAS_30
访问地址	http://ip:port/context-path/swagger-ui.html	http://ip:port/context-path/swagger-ui/index.html

访问地址记得拼接服务名，如果没有在配置文件中配置服务名，可以忽略。

1、pom文件中引入Swagger依赖

Swagger2

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

这里使用的Swagger版本是2.9.2、Springboot 版本是2.5.14，如果使用的Springboot版本过高，启动会报错。Springboot版本在2.6以下即可正常启动。

Swagger3

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

这里使用的Springboot版本是2.7.6，启动正常。

Springboot版本到2.6.0以上，启动报错 Failed to start bean ‘documentationPluginsBootstrapper‘ 问题处理

原因：Spring Boot 2.6.0开始使用基于PathPatternParser的路径匹配，而Springfox版本一直没有更新还是使用的AntPathMatcher导致了这个问题。

解决：修改yaml文件，将SpringBoot路劲匹配模式修改为AntPathMatcher就可以了，配置如下：

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

使用swagger-bootstrap-ui

<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.9.6</version>
</dependency>

引入依赖后启动项目访问地址变成：http://ip:port/content-path/doc.html

2、swagger配置

Swagger2

@Configuration
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("1.0")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger2 RestFul APIs")
                .description("swagger2接口文档")
                .contact(new Contact("xx", "http://blog.csdn.net", "xx@email.com"))
                .version("1.0")
                .build();
    }
}

Swagger3

@Configuration
@EnableOpenApi
public class Swagger3Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("1.0")
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("swagger3 RestFul APIs")
                .description("swagger3接口文档")
                .contact(new Contact("xx", "http://blog.csdn.net", "xx@email.com"))
                .version("1.0")
                .build();
    }
}