替代 Springfox Swagger 的 SpringDoc 入门（一）

之前在 Spring Boot 项目中使用的是 Springfox 提供的 Swagger 库自动化生成API文档，近期发现 Springfox Swagger2 3.0自2020年7月14日至今已经2年多没更新了，同时对Spring Boot 2.6.0 以上的版本支持不是太好，网上搜索替代方案发现了另一款 Swagger 库 SpringDoc，其支持Spring WebMvc、Spring WebFlux、Spring Data Rest和Spring Security等项目，官网：https://springdoc.org/ 。总体概述图如下：

0. 引入 SpringDoc 步骤：

graph LR A(1.在 pom 中引入 SpringDoc 依赖) --> B(2.添加 Config 配置) B--> C(3.代码中增加注解)

1. 添加依赖

在 pom.xml 加入以下内容，即可开始使用：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
</dependency>

注（2023.10.26 变更）：

1. For spring-boot v3 support, make sure you use springdoc-openapi v2.2.0
2. springdoc-openapi v1.7.0 is the latest Open Source release supporting Spring Boot 2.x and 1.x.

2. 添加 Config 配置描述信息

/**
 * SpringDoc API 文档相关配置
 */
@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI springOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("SpringDoc API Test")
                        .description("SpringDoc Simple Application Test")
                        .version("v0.0.1")
                        .license(new License().name("Apache 2.0").url("https://www.apache.org/licenses/LICENSE-2.0")))
                .externalDocs(new ExternalDocumentation()
                        .description("替代 Springfox 的 SpringDOC 入门 文档")
                        .url("https://www.cnblogs.com/jddreams/p/15922674.html"));
    }

}

3. 在 Controller 中使用注解标记文本

@RestController
@Tag(name="/getString")
public class SpringDocController {

    @Operation(summary = "This SpringDoc Test One.")
    @GetMapping
    public String getClients() {
        return "Hello First SpringDoc Application!";
    }

}

4. 查看 swagger 文档

启动应用

• swagger 文档在以下 URL 中提供：http://localhost:8080/swagger-ui/index.html

• json 格式的 OpenAPI 3.0.1 描述将在以下 URL 中提供： http:localhost:8080/v3/api-docs 。

• yaml 格式在以下 URL 中提供：/v3/api-docs.yaml

对于 HTML 格式的 swagger 文档的自定义路径，在 config 文件中添加自定义 springdoc 属性：.

# swagger-ui custom path
springdoc.swagger-ui.path=/swagger-ui.html

5. 从SpringFox迁移

用 SpringDoc 替换 SpringFox 经常使用的Swagger注解（swagger 3 注释包含在springdoc-openapi-ui依赖项中，swagger 3 注释的包是io.swagger.v3.oas.annotations）。

SpringFox	SpringDoc
@Api	@Tag
@ApiIgnore	@Parameter(hidden = true)或@Operation(hidden = true)或@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")

6. springdoc-openapiwith 与 spring-boot 的兼容性

springdoc-openapi v1 与 springboot、springboot2 兼容。
springdoc-openapi v2 与 springboot3兼容
以上对应关系不能搞错。

spring-boot 版本	最低 springdoc-openapi 版本
3.x	2.0+
2.6.x,1.5.x	1.6.0+
2.5.x,1.5.x	1.5.9+
2.4.x,1.5.x	1.5.0+
2.3.x,1.5.x	1.4.0+
2.2.x,1.5.x	1.2.1+
2.0.x,1.5.x	1.0.0+