Springdoc-- 解决Swagger2与SpringBoot3版本以上不兼容的问题以及日常使用

springboot版本：3.2.0

在使用Swagger2的时候会发生项目启动报错

为什么使用Springdoc

springdoc-openapijava库有助于使用spring引导项目自动生成API文档。springdoc-openapi通过在运行时检查应用程序来根据spring配置、类结构和各种注释推断API语义。

自动生成JSON/YAML和HTML格式API的文档。此文档可以通过使用swaggerapi注释的注释来完成。

此库支持：

OpenAPI 3

Spring boot v3（Java 17和Jakarta EE 9）

JSR-303，专门针对@NotNull、@Min、@Max和@Size。

Swagger ui

OAuth 2

GraalVM本机映像

解决：

使用Springdoc替换Swagger2

初始启动：

以后使用可以慢慢调整

添加依赖包

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
    <version>2.3.0</version>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

配置一个文件

@Configuration
public class SwaggerConfig {


    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("SpringShop API")
                        .description("Spring shop sample application")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("http://springdoc.org")))
                .externalDocs(new ExternalDocumentation()
                        .description("SpringShop Wiki Documentation")
                        .url("https://springshop.wiki.github.org/docs"));
    }

}

修改springboot的yml配置

springdoc:
  swagger-ui:
    # 禁止默认路径
    disable-swagger-default-url: true

模块配置(需要可配置，不需要可不配置 )

 @Bean
  public GroupedOpenApi publicApi() {
      return GroupedOpenApi.builder()
              .group("springshop-public")
              .pathsToMatch("/public/**")
              .build();
  }
  @Bean
  public GroupedOpenApi adminApi() {
      return GroupedOpenApi.builder()
              .group("springshop-admin")
              .pathsToMatch("/admin/**")
              .addOpenApiMethodFilter(method -> method.isAnnotationPresent(Admin.class))
              .build();
  }

注解使用替换

• @Api → @Tag

• @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden

• @ApiImplicitParam → @Parameter

• @ApiImplicitParams → @Parameters

• @ApiModel → @Schema

• @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)

• @ApiModelProperty → @Schema

• @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")

• @ApiParam → @Parameter

• @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")

测试

测试路径：访问路径+Swagger-ui/index.html

再细化内容可参考Springdoc官方文档。

OpenAPI 3 Library for spring-boot