springBoot整合Swagger3踩过的坑(idea)----failed to parse configuration....

---

前言

随着swagger2不在维护,为方便进行前后端接口的调试,决定将swagger2升级到swagger3,此处,我做了个swagger3+springBoot demo,记录途中遇到的问题,给大家提供一些解决思路

---

一、新建一个SpringBoot项目

首先新建一个springboot项目

1. 第一步:点击file新建一个project,如图:选择Spring Initializr,点击next
   
2. 第二步: 选择java版本号,默认是8,如图,完成之后点击next
   
3. 第三步: 选择依赖(因为是demo,默认选择spring web,当然大家也可以根据自己需求选择)
   
4. 第四步:新建项目名,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. 写一个测试例子,重新运行项目

1. 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;
    }
}

3. SwaggerController(引入swagger Api 和ApiOperation 注解)

@Api(tags = "操作接口")
@RestController
@RequestMapping("hs")
public class SwaggerController {

    @PostMapping("/getUser")
    @ApiOperation("获取用户信息")
    public UserPo getUser(UserPo po){
        return po;
    }
}

5. application.properties (我没有进行任何配置,大家根据自己需求决定)
6. 运行效果如下:
   
   

5.swagger2和swagger3的区别

1. swagger2 目前已经不在进行技术支持,持续使用出现问题无法解决
2. swagger2的访问方式是:http://localhost:8080/ swagger-ui.html
3. swagger3的访问方式是:http://localhost:8080/ swagger-ui/index.html
4. swagger3界面方式和swagger的界面有所优化,体验效果更好!

---