SpringBoot整合Swagger3踩过的坑
前言
随着swagger2不在维护,为方便进行前后端接口的调试,决定将swagger2升级到swagger3,此处,我做了个swagger3+springBoot demo,记录途中遇到的问题,给大家提供一些解决思路一、新建一个SpringBoot项目
首先新建一个springboot项目
- 第一步:点击file新建一个project,如图:选择Spring Initializr,点击next
- 第二步: 选择java版本号,默认是8,如图,完成之后点击next
- 第三步: 选择依赖(因为是demo,默认选择spring web,当然大家也可以根据自己需求选择)
- 第四步:新建项目名,finish即可,新的项目建立完成
二、引入swagger3依赖并解决问题
1.新建完项目默认pom中依赖
pom中默认依赖如下(lombok,junit-jupiter是新建项目后加入的):
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.0.5.RELEASE</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.example</groupId>
<artifactId>demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>demo</name>
<description>Demo project for Spring Boot</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>RELEASE</version>
<scope>test</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
2.引入swagger3 之后运行出现问题
pom中新增swagger依赖如下:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<version>3.0.0</version>
</dependency>
同时在application中增加注解EnableOpenApi
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;
@SpringBootApplication
@EnableOpenApi
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
运行项目出现如下问题:
3. 解决方法
1. 一开始一直以为是导入的依赖有问题,是不是swagger3的依赖还有其他方式,查了很多,导入依赖的包都一样,后来研究报错,发现可能是其他依赖包发生相互冲突了
2. 解决方式,修改pom中的依赖如下(排除掉swagger中的spring-plugin-core组件,重新导入该组件,版本和parent中的版本保持一个版本即可)
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-boot-starter</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.plugin</groupId>
<artifactId>spring-plugin-core</artifactId>
</exclusion>
</exclusions>
<version>3.0.0</version>
</dependency>
<dependency>
<groupId>org.springframework.plugin</groupId>
<artifactId>spring-plugin-core</artifactId>
<version>2.0.0.RELEASE</version>
</dependency>
4.配置swagger(完整项目代码)
1. 将DemoApplication中EnableOpenApi去掉,写到swagger的配置文件中如上图的config包中SwaggerConfig中
2. 写一个测试例子,重新运行项目
- SwaggerConfig中的代码如下
@EnableOpenApi
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
//swagger设置,基本信息,要解析的接口及路径等
return new Docket(DocumentationType.OAS_30)
.apiInfo(apiInfo())
.select()
//设置通过什么方式定位需要自动生成文档的接口,这里定位方法上的@ApiOperation注解
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//接口URI路径设置,any是全路径,也可以通过PathSelectors.regex()正则匹配
.paths(PathSelectors.any())
.build();
}
//生成接口信息,包括标题、联系人,联系方式等
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger3接口文档")
.description("自己的项目描述,自定义")
.contact(new Contact("联系人", "访问地址", "邮箱"))
.version("1.0")
.build();
}
}
2 . UserPo 代码(在实体中引入swagger中的api ApiModel和ApiModelProperty)
@ApiModel("用户信息")
public class UserPo implements Serializable {
@ApiModelProperty("id")
private Long id;
@ApiModelProperty("用户名")
private String username;
public Long getId() {
return id;
}
public void setId(Long id) {
this.id = id;
}
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
}
- SwaggerController(引入swagger Api 和ApiOperation 注解)
@Api(tags = "操作接口")
@RestController
@RequestMapping("hs")
public class SwaggerController {
@PostMapping("/getUser")
@ApiOperation("获取用户信息")
public UserPo getUser(UserPo po){
return po;
}
}
- application.properties (我没有进行任何配置,大家根据自己需求决定)
- 运行效果如下:
5.swagger2和swagger3的区别
- swagger2 目前已经不在进行技术支持,持续使用出现问题无法解决
- swagger2的访问方式是:http://localhost:8080/ swagger-ui.html
- swagger3的访问方式是:http://localhost:8080/ swagger-ui/index.html
- swagger3界面方式和swagger的界面有所优化,体验效果更好!