Springdoc-OpenAPI 使用教程

最新推荐文章于 2025-05-12 09:00:00 发布

原创最新推荐文章于 2025-05-12 09:00:00 发布 · 658 阅读

5 ·

CC 4.0 BY-SA版权

HyperledgerFabric是一个Linux基金会领导的开源项目，提供模块化设计和多种共识机制，适用于企业场景。它强调隐私、安全，应用于供应链管理、金融交易等，是构建高效、透明和可信赖业务网络的有力工具。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

Springdoc-OpenAPI 使用教程

springdoc-openapi Library for OpenAPI 3 with spring-boot 项目地址: https://gitcode.com/gh_mirrors/sp/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 文档。