SpringBoot 3.x项目如何用SpringDoc OpenAPI一键生成Swagger文档（附完整配置）

SpringBoot 3.x 项目实战：从零到一构建企业级 OpenAPI 文档中心

在微服务架构和前后端分离成为主流的今天，清晰、准确、可交互的 API 文档不再是“锦上添花”，而是项目协作的“生命线”。对于已经拥抱 Spring Boot 3.x 和 JDK 17+ 技术栈的团队来说，一个现实且紧迫的问题是：我们熟悉的 springfox（Swagger 2.x）已经无法兼容，文档工具链的升级迫在眉睫。这正是SpringDoc OpenAPI大显身手的舞台。它不仅仅是一个简单的替代品，更是一个基于 OpenAPI 3.x 规范的现代化文档解决方案，能够无缝集成到你的 Spring Boot 3.x 项目中，实现从代码到文档的“一键生成”。本文将从一个资深开发者的实战视角出发，手把手带你完成从依赖引入、基础配置、高级定制到安全集成的全流程，目标是打造一个开箱即用、符合企业级规范的可视化 API 文档中心。

1. 环境准备与依赖配置：告别 springfox，拥抱 SpringDoc

升级到 Spring Boot 3.x 后，许多开发者遇到的第一个拦路虎就是原先的springfox-boot-starter无法启动，控制台会抛出关于PathPatternParser等类的ClassNotFoundException。这是因为 Spring Boot 3.x 底层迁移到了 Jakarta EE 9+ 的命名空间，而 springfox 的维护已经停滞，未能跟上这次重大变更。因此，我们的第一步就是彻底移除旧依赖，引入新的解决方案。

1.1 清理旧依赖与引入 SpringDoc

在你的pom.xml文件中，首先确保移除了所有与springfox或swagger相关的旧依赖，例如springfox-boot-starter、springfox-swagger2、springfox-swagger-ui。然后，添加 SpringDoc 的核心依赖。

对于标准的 Spring Boot Web MVC 项目，最常用的是springdoc-openapi-starter-webmvc-ui。这个 starter 包一次性引入了 OpenAPI 核心库和 Swagger UI 界面，真正做到开箱即用。

<dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> <version>2.5.0</version> <!-- 请使用最新稳定版本 --> </dependency>

版本选择小贴士：SpringDoc 的主版本号（如 2.x）与 Spring Boot 3.x 保持兼容。建议始终使用官方仓库中的最新稳定版，以获得最佳的性能和最多的功能特性。你可以通过 Maven Central 查询最新版本。

1.2 基础配置与自动生效

引入依赖后，无需任何额外配置，SpringDoc 的魔法就已经开始生效了。它会在应用启动时，自动扫描所有被@RestController、@RequestMapping、@GetMapping等注解标记的控制器，并基于这些信息生成符合 OpenAPI 3.0 规范的 JSON 描述。

启动你的 Spring Boot 3.x 应用，然后打开浏览器，访问以下两个默认地址，你将立即看到成果：

如果能看到清晰的 UI 界面或结构化的 JSON 数据，恭喜你，SpringDoc 已经成功集成。但此时生成的文档还比较“简陋”，只有基础的路径和 HTTP 方法信息。接下来，我们将通过注解来丰富它。

2. 使用注解精细化你的 API 文档

SpringDoc 提供了一套与 OpenAPI 规范对齐的注解，让我们可以在编写业务代码的同时，以声明式的方式为 API 添加详细的描述。这比维护一份独立的文档要可靠和高效得多。

2.1 控制器与接口级别的注解

首先，我们可以使用@Tag注解对整个控制器进行分类。这相当于给一组相关的 API 打上标签，在 Swagger UI 中会以分组的形式展示，极大提升了文档的可读性。

@RestController @RequestMapping("/api/v1/users") @Tag(name = "用户管理", description = "用户相关的所有操作，包括增删改查") public class UserController { // ... 控制器方法 }

在具体的 API 方法上，@Operation注解是核心，用于描述这个接口是做什么的。

@GetMapping("/{id}") @Operation( summary = "根据ID查询用户", description = "通过用户的主键ID获取用户的详细信息。如果用户不存在，将返回404状态码。", parameters = { @Parameter(name = "id", description = "用户唯一标识", required = true, example = "123") } ) public ResponseEntity<UserDTO> getUserById(@PathVariable Long id) { // ... 业务逻辑 }

@Parameter注解可以内嵌在@Operation中，也可以直接用在方法参数上，用于描述请求参数（如路径参数、查询参数、请求头等）。

2.2 模型与数据结构的描述

API 的请求体和响应体模型同样需要清晰的文档。@Schema注解用于描述模型类的字段。

public class UserDTO { @Schema(description = "用户ID", example = "1001", accessMode = Schema.AccessMode.READ_ONLY) private Long id; @Schema(description = "用户名", example = "zhangsan", minLength = 3, maxLength = 20) @NotBlank private String username; @Schema(description = "用户邮箱", example = "user@example.com", format = "email") @Email private String email; // getters and setters }

通过example属性提供示例值，能让前端开发者更直观地理解数据结构。minLength、maxLength、format等属性还能与 Bean Validation 注解（如@NotBlank,@Email）协同，在文档中展示出验证规则。

2.3 响应与状态码的声明

一个专业的 API 文档必须明确说明各种可能的响应。@ApiResponse注解可以清晰地定义不同 HTTP 状态码对应的响应内容和描述。

@PostMapping @Operation(summary = "创建新用户") @ApiResponses(value = { @ApiResponse(responseCode = "201", description = "用户创建成功", content = @Content(schema = @Schema(implementation = UserDTO.class))), @ApiResponse(responseCode = "400", description = "请求参数无效", content = @Content(schema = @Schema(implementation = ErrorResponse.class))), @ApiResponse(responseCode = "409", description = "用户名已存在") }) public ResponseEntity<UserDTO> createUser(@Valid @RequestBody CreateUserRequest request) { // ... 业务逻辑 }

提示：为常见的错误状态码（如 400, 401, 403, 404, 500）定义统一的响应模型（如ErrorResponse），并在文档中声明，能极大提升 API 的易用性和可维护性。

3. 高级配置与企业级定制

当项目规模扩大，拥有数十甚至上百个 API 时，默认的单一文档页面会变得臃肿不堪。同时，不同模块（如对外公开 API 和内部管理 API）可能需要对不同的开发者群体开放。SpringDoc 强大的分组功能和自定义配置能力在此刻显得尤为重要。

3.1 API 分组管理

通过定义GroupedOpenApiBean，我们可以将 API 按照路径、包名等规则进行逻辑分组。这是管理大型项目 API 文档的推荐方式。

@Configuration public class OpenApiGroupConfig { @Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("public-apis") // 分组标识 .pathsToMatch("/api/public/**") // 匹配以 /api/public/ 开头的路径 .addOpenApiCustomizer(openApi -> openApi.info(new Info() .title("公开API文档") .version("v1") .description("面向第三方合作伙伴开放的接口"))) .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("admin-apis") .pathsToMatch("/api/admin/**", "/internal/**") .packagesToScan("com.yourcompany.admin") // 也可以按包扫描 .build(); } @Bean public GroupedOpenApi allApis() { return GroupedOpenApi.builder() .group("all") .pathsToMatch("/api/**") .build(); } }

配置完成后，Swagger UI 的访问方式会发生变化：

• 默认页面 (/swagger-ui.html) 顶部会出现一个下拉选择框，用于切换不同的分组。
• 你也可以直接通过 URL 访问特定分组的 UI，例如：/swagger-ui.html?group=public-apis。
• 分组后的 OpenAPI JSON 描述地址也变为：/v3/api-docs/{group}，如/v3/api-docs/admin-apis。

3.2 全局 OpenAPI 元信息定制

除了分组信息，我们通常还需要定义整个 API 文档的全局信息，如项目标题、版本、描述、联系人、许可证等。这可以通过创建一个OpenAPIBean 来实现。

@Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("企业级订单管理系统 API") .version("1.0.0") .description("本系统提供完整的订单生命周期管理接口。") .contact(new Contact() .name("技术支撑团队") .email("tech-support@yourcompany.com")) .license(new License() .name("Apache 2.0") .url("http://springdoc.org"))) .externalDocs(new ExternalDocumentation() .description("项目 Wiki 文档") .url("https://wiki.yourcompany.com/order-system")) .addSecurityItem(new SecurityRequirement().addList("bearerAuth")) // 全局安全要求 .components(new Components() .addSecuritySchemes("bearerAuth", new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))); }

这个配置不仅美化了文档的头部信息，还定义了一个名为bearerAuth的全局安全方案（使用 JWT Bearer Token）。在 Swagger UI 中，右上角会出现一个“Authorize”按钮，测试者可以在此处填入 Token，后续所有接口的测试请求都会自动带上Authorization: Bearer <token>请求头。

3.3 自定义 Swagger UI 界面

如果你觉得默认的 Swagger UI 样式或配置不符合团队习惯，SpringDoc 也允许你进行深度定制。

@Bean public SwaggerUiConfigProperties swaggerUiConfig() { SwaggerUiConfigProperties config = new SwaggerUiConfigProperties(); // 禁用语法高亮，某些内网环境加载高亮库慢 config.setSyntaxHighlight(new SwaggerUiConfigProperties.SyntaxHighlight()); config.getSyntaxHighlight().setActivated(false); // 设置默认的文档展开模式为“不展开” config.setDocExpansion(DocExpansion.NONE); // 修改 Swagger UI 的默认路径（可选，通常不建议修改） // config.setPath("/my-docs"); return config; }

你还可以通过实现SwaggerUiOAuthProperties或提供自定义的IndexPageTransformerBean 来修改 UI 的 HTML 内容，实现更彻底的界面定制，但这通常只在有特殊品牌化需求时才需要。

4. 与 Spring Security 的安全集成

在实际企业环境中，API 文档本身可能也需要进行访问控制，防止未授权的人员查看内部接口。当项目集成了 Spring Security 时，我们需要显式地放行 Swagger UI 和相关 API 文档 JSON 的访问路径。

4.1 配置安全放行规则

以下是一个基于 Spring Security 6.x（与 Spring Boot 3.x 配套）的配置示例，它允许未经认证即可访问所有 Swagger 资源。

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.web.SecurityFilterChain; import static org.springframework.security.config.Customizer.withDefaults; @Configuration @EnableWebSecurity public class SecurityConfig { @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz // 放行 Swagger UI 相关资源 .requestMatchers( "/swagger-ui.html", "/swagger-ui/**", // Swagger UI 的静态资源（JS, CSS） "/v3/api-docs/**", // OpenAPI JSON 描述文件 "/webjars/**", // Swagger UI 依赖的 webjar "/swagger-resources/**" ).permitAll() // 其他所有请求都需要认证 .anyRequest().authenticated() ) // 可以使用表单登录、OAuth2、JWT等其他认证方式 .formLogin(withDefaults()) .httpBasic(withDefaults()); return http.build(); } }

注意：上述配置是一个最简单的示例。在生产环境中，你可能需要根据实际情况调整放行策略，例如将文档访问权限与特定的用户角色绑定，或者仅在内网 IP 段内放行。

4.2 在受保护的 API 中进行测试

当你在 Swagger UI 中测试那些需要认证的接口时，有几种方式可以传递凭证：

1. 使用全局安全方案：如前文customOpenAPI()配置中定义的bearerAuth，在 UI 的 “Authorize” 对话框中填入 Token。
2. 使用@SecurityRequirement注解：在控制器或方法级别声明所需的安全方案。

   @RestController @SecurityRequirement(name = "bearerAuth") // 声明整个控制器需要认证 public class SecureController { @GetMapping("/secure-data") public String getSecureData() { ... } }

3. 手动添加请求头：Swagger UI 的每个接口测试区域都支持手动添加请求头，你可以临时添加Authorization: Bearer your_token_here。

5. 生产环境部署与优化建议

将带有 Swagger 文档的应用部署到生产环境时，我们通常不希望对外暴露文档界面。以下是一些常见的实践和优化技巧。

动态控制文档的启用：通过配置文件，可以轻松地在不同环境（开发、测试、生产）中开关 Swagger UI。

# application-dev.yml springdoc: swagger-ui: enabled: true path: /swagger-ui.html api-docs: enabled: true path: /v3/api-docs # application-prod.yml springdoc: swagger-ui: enabled: false # 生产环境禁用 UI api-docs: enabled: true # 但可以保留 JSON 端点，供内部工具使用 path: /internal/v3/api-docs # 并修改为不易猜测的路径

生成离线文档：你可以定期访问/v3/api-docs端点，将返回的 JSON 文件保存下来。然后使用 Swagger Codegen 或 OpenAPI Generator 工具，将其生成为静态 HTML、PDF 或 Word 文档，分发给需要离线阅读的团队成员或客户。

性能考量：SpringDoc 在启动时的扫描和运行时生成 JSON 会有微小的性能开销。对于超大型项目（数千个接口），可以考虑：

• 更精细地使用分组，避免一次性加载所有 API。
• 在非开发环境中，通过配置springdoc.api-docs.enabled=false完全禁用文档生成功能。
• 使用@Hidden注解隐藏那些不需要暴露给文档的控制器或方法。

从我的项目经验来看，SpringDoc 的引入极大地提升了团队协作效率。前端同事不再需要反复询问接口细节，测试人员也能基于清晰的文档提前设计用例。最关键的是，文档与代码的同步是自动的，避免了“代码已改，文档未更”的尴尬局面。对于 Spring Boot 3.x 项目，SpringDoc 是目前最成熟、最优雅的 API 文档解决方案，值得你花时间将其集成到你的开发流程中。