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();
}
}