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.springfoxgroupId>
    <artifactId>springfox-swagger2artifactId>
    <version>2.9.2version>
dependency>
<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-swagger-uiartifactId>
    <version>2.9.2version>
dependency>

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

Swagger3

<dependency>
    <groupId>io.springfoxgroupId>
    <artifactId>springfox-boot-starterartifactId>
    <version>3.0.0version>
dependency>

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

使用swagger-bootstrap-ui

<dependency>
    <groupId>com.github.xiaoymingroupId>
    <artifactId>swagger-bootstrap-uiartifactId>
    <version>1.9.6version>
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", "[email protected]"))
                .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", "[email protected]"))
                .version("1.0")
                .build();
    }
}