【亲测免费】 Springdoc-OpenAPI 使用教程

2026-01-14 18:45:07作者：翟江哲Frasier

1. 项目介绍

Springdoc-OpenAPI 是一个用于自动化生成 API 文档的 Java 库，适用于 Spring Boot 项目。它通过在运行时检查应用程序来推断 API 语义，基于 Spring 配置、类结构和各种注解生成文档。生成的文档可以以 JSON/YAML 和 HTML 格式呈现，并且可以通过 Swagger-API 注解进行补充。

Springdoc-OpenAPI 支持以下特性：

OpenAPI 3
Spring Boot v3 (Java 17 & Jakarta EE 9)
JSR-303 注解（如 @NotNull, @Min, @Max, @Size）
Swagger-ui
OAuth 2
GraalVM 原生镜像

2. 项目快速启动

2.1 添加依赖

首先，在你的 Spring Boot 项目中添加 springdoc-openapi-ui 依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>last-release-version</version>
</dependency>

2.2 配置 Swagger UI 路径

你可以在 application.properties 或 application.yml 中配置 Swagger UI 的路径：

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

2.3 启动应用

启动你的 Spring Boot 应用后，访问以下 URL 即可查看生成的 API 文档：

http://server:port/context-path/swagger-ui.html

其中：

server: 服务器名称或 IP
port: 服务器端口
context-path: 应用的上下文路径

3. 应用案例和最佳实践

3.1 案例一：Spring Boot 2 Web MVC 项目

在 Spring Boot 2 Web MVC 项目中使用 Springdoc-OpenAPI 生成 API 文档。

@RestController
@RequestMapping("/api")
public class MyController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

启动应用后，访问 http://localhost:8080/swagger-ui.html 即可查看生成的 API 文档。

3.2 案例二：Spring Boot 3 WebFlux 项目

在 Spring Boot 3 WebFlux 项目中使用 Springdoc-OpenAPI 生成 API 文档。

@RestController
@RequestMapping("/api")
public class MyController {

    @GetMapping("/hello")
    public Mono<String> sayHello() {
        return Mono.just("Hello, World!");
    }
}