在前后端分离和微服务盛行的今天，API 文档是团队协作的“通用语言”。一份清晰、准确、实时同步的文档，能极大提升开发和联调效率。然而，手动编写和维护 API 文档（如 Word、Markdown 或 Postman）是一场永无止境的噩梦——它总是滞后于代码的变更。

曾经，Springfox (Swagger 2) 是这个领域的王者，但随着 Spring Boot 3.x 的到来，它已廉颇老矣。现在，SpringDoc OpenAPI 凭借其与 Spring Boot 的无缝集成和对 OpenAPI 3 规范的全面支持，成为了当之无愧的“终极解决方案”。

本文将带你从零开始，深入探索 SpringDoc 的使用，从快速集成到精细化定制，让你彻底告别手写文档的痛苦。

1. 为什么选择 SpringDoc？

在2025年的今天，对于任何新的 Spring Boot 项目，选择 SpringDoc 而非其前辈 Springfox 的理由非常充分：

• • 无缝集成 Spring Boot 3.x: SpringDoc 是为现代 Spring Boot 版本量身打造的，能完美兼容 Spring Framework 6.x 和 Jakarta EE 9+。

• • 支持 OpenAPI 3 规范: OpenAPI 3 是 API 描述的最新行业标准，提供了更丰富、更强大的规范定义能力。

• • 自动化程度高: 无需繁琐的注解（如 @Api、@ApiModel），SpringDoc 能自动从你的 Spring Web 注解中推断出大量信息。

• • 社区活跃: 项目正在积极开发和维护，能快速响应社区问题并跟进 Spring Boot 的更新。

2. 快速上手：三步集成交互式 API 文档

在 Spring Boot 项目中集成 SpringDoc 极其简单，真正做到了“开箱即用”。

第一步：添加依赖 (Maven)

只需在你的 pom.xml 中添加一个依赖即可。

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

如果你使用 WebFlux，请将 webmvc 替换为 webflux。

第二步：运行你的 Spring Boot 应用

没错，就是这样。你不需要添加任何额外的注解或配置类，只需正常启动你的应用。

第三步：访问 API 文档

启动成功后，打开浏览器访问以下两个地址：

1. 1. 交互式 UI 界面: http://localhost:8080/swagger-ui.html

2. 2. OpenAPI 规范 (JSON格式): http://localhost:8080/v3/api-docs

你会看到一个由 Swagger UI 提供的、功能齐全的交互式文档页面。它已经自动扫描了你项目中所有的 @RestController，并将其API展示了出来。

(这是一个示例图片链接，实际效果类似)

3. 用注解“精雕细琢”你的 API 文档

自动生成的基础文档虽然可用，但缺少描述、示例等关键信息。为了让文档更专业、更易于理解，我们需要使用 OpenAPI 3 的注解来“精雕细琢”。

核心注解:

• • @Tag: 用于为 Controller 进行分组和描述。

• • @Operation: 用于描述一个具体的 API 操作（方法）。

• • @Parameter: 用于描述一个方法的参数。

• • @Schema: 用于描述一个模型（DTO/VO）或其属性。

• • @ApiResponses / @ApiResponse: 用于描述可能的响应状态和内容。

实战示例：

UserDTO.java (数据传输对象)

import io.swagger.v3.oas.annotations.media.Schema;// 使用 @Schema 描述整个类
@Schema(description = "用户视图对象")
public class UserDTO {@Schema(description = "用户ID", example = "1001")private Long id;@Schema(description = "用户名", requiredMode = Schema.RequiredMode.REQUIRED, example = "Alice")private String username;// ... Getters and Setters
}

UserController.java (控制器)

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api/users")
// 使用 @Tag 为整个 Controller 分组
@Tag(name = "用户管理", description = "提供用户的增删改查功能")
public class UserController {@GetMapping("/{id}")// 使用 @Operation 描述方法@Operation(summary = "根据ID获取用户", description = "传入用户ID，返回单个用户信息")// 使用 @Parameter 描述参数@Parameter(name = "id", description = "用户ID", required = true, example = "1001")// 使用 @ApiResponses 描述所有可能的响应@ApiResponses({@ApiResponse(responseCode = "200", description = "成功找到用户"),@ApiResponse(responseCode = "404", description = "用户未找到")})public UserDTO getUserById(@PathVariable Long id) {// ... 业务逻辑 ...return new UserDTO(id, "Alice");}@PostMapping@Operation(summary = "创建新用户")public UserDTO createUser(@RequestBody UserDTO user) {// ... 业务逻辑 ...return user;}
}

添加这些注解后，再次刷新 swagger-ui.html，你会发现文档变得极其清晰、专业，包含了分组、描述、示例值和所有可能的响应码。

4. 全局配置：打造专业的 API 门户

除了针对单个 API 的注解，我们还需要配置文档的全局信息，如标题、版本、联系人、安全认证方案等。推荐使用定义 OpenAPI Bean 的方式，因为它最灵活。

在任意 @Configuration 类中添加以下 Bean：

import io.swagger.v3.oas.models.Components;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.security.SecurityRequirement;
import io.swagger.v3.oas.models.security.SecurityScheme;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class OpenApiConfig {@Beanpublic OpenAPI customOpenAPI() {// 定义 JWT Bearer 认证方案final String securitySchemeName = "bearerAuth";return new OpenAPI()// 1. 定义全局信息.info(new Info().title("我的应用 API").description("这是一个强大应用的 API 文档").version("v1.0.0"))// 2. 添加全局安全认证需求.addSecurityItem(new SecurityRequirement().addList(securitySchemeName))// 3. 在 Components 中定义安全认证方案的细节.components(new Components().addSecuritySchemes(securitySchemeName,new SecurityScheme().name(securitySchemeName).type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));}
}

配置此 Bean 后，Swagger UI 的右上角会出现一个“Authorize”按钮，允许开发者输入 JWT Token，从而方便地测试需要认证的接口。

5. 进阶技巧与最佳实践

• • 接口分组 (GroupedOpenApi): 如果你想为不同的 API 集合（如“对内API”和“对外API”）生成不同的文档，可以定义多个 GroupedOpenApi 类型的 Bean。

• • 保护文档端点: 在生产环境中，API 文档不应公开访问。你需要使用 Spring Security 来保护 /swagger-ui.html 和 /v3/api-docs 等相关路径，只允许特定角色的用户访问。

• • 利用校验注解: SpringDoc 会自动识别 JSR 303 / Jakarta Bean Validation 的注解（如 @NotNull, @Size, @Pattern），并将这些校验规则展示在文档中，这是非常有用的特性。

总结

在现代 Spring Boot 项目中，SpringDoc OpenAPI 已经不再是一个“锦上添花”的工具，而是保障团队高效协作、提升项目专业度的核心基础设施。