替代 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+