SpringBoot3.x整合Swagger(解决swagger2、swagger3不兼容问题)

SpringBoot3.x整合Swagger

SpringBoot3整合Swagger注意事项

SpringBoot3+jdk17的情况下，swagger的V2和V3都是不行的。这里使用spring官方出品的springdoc-openapi。在使用springdoc-openapi的时候也有很多坑，首先springdoc-openapi的v1.x.x版本也是不行的**，springdoc-openapi的版本必须是v2.x.x以上。**

常用注解

注解SpringBoot3 版本	替换旧注解 SpringBoot2 版本	描述
@Tag	@Api	用于标注一个Controller（Class）。在默认情况下，Swagger-Core只会扫描解析具有@Api注解的类，而会自动忽略其他类别资源（JAX-RS endpoints，Servlets等等）的注解。
@Operation	@ApiOperation	用于对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。
@Parameter	@ApiParam	@Parameter作用于请求方法上，定义api参数的注解。
@Parameters、@Parameter	@ApiImplicitParams、@ApiImplicitParam	都可以定义参数 （1）@Parameters：用在请求的方法上，包含一组参数说明 （2）@Parameter：对单个参数的说明
io.swagger.v3.oas.annotations新包中的@ApiResponses、@ApiResponse	旧包io.swagger.annotations中的@ApiResponses、@ApiResponse	进行方法返回对象的说明。
@Schema	@ApiModel、@ApiModelProperty	@Schema用于描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景）。

整合

依赖

       <!-- openAPI包，替换 Swagger 的 SpringFox -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.2.0</version>
        </dependency>
<!--        基础依赖-->

			  <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>

配置类

@Configuration
public class OpenApiConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("接口文档标题")                         //swagger接口文档名称
                        .description("SpringBoot3 集成 Swagger3接口文档")       //swagger接口文档描述
                        .version("v1"))                  //版本
                .externalDocs(new ExternalDocumentation()        //附加文档
                        .description("项目API文档")             //附加文档名称
                        .url("/"));                         //附加文档地址
    }

}

配置文件

application.yaml

spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

controller

@Tag(name = "控制器：测试Swagger3", description = "描述：测试Swagger3") //new
@RestController
@RequestMapping("/log")
public class SwaggerController {

    @Operation(summary = "测试swagger",description = "测试描述")
    @GetMapping("/test")
    public void test(){
        System.out.println("hello");
    }
}