告别手写文档！Spring Boot API 文档终极解决方案：SpringDoc OpenAPI

在前后端分离和微服务盛行的今天，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. 交互式 UI 界面: http://localhost:8080/swagger-ui.html
1. 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 {

    @Bean
    public 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 已经不再是一个"锦上添花"的工具，而是保障团队高效协作、提升项目专业度的核心基础设施。