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

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!");
    }
}

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

4. 典型生态项目

4.1 Spring Boot

Springdoc-OpenAPI 与 Spring Boot 紧密集成，支持 Spring Boot 2.x 和 3.x 版本。

4.2 Swagger UI

Springdoc-OpenAPI 自动部署 Swagger UI，提供友好的 API 文档界面。

4.3 Spring Security

Springdoc-OpenAPI 支持 Spring Security，可以自动生成包含安全信息的 API 文档。

4.4 Spring Data Rest

Springdoc-OpenAPI 支持 Spring Data Rest，可以自动生成与数据资源相关的 API 文档。

通过以上步骤，你可以快速上手并使用 Springdoc-OpenAPI 生成高质量的 API 文档。