Java 后端 / 系统课时
生成并维护 OpenAPI 文档
生成并维护 OpenAPI 文档
本课将把控制器、请求模型、响应示例和鉴权要求汇总为可访问的 OpenAPI 文档,并建立随代码演进同步维护的做法,最终可通过 JSON 契约和 Swagger UI 检查接口说明是否完整。
学习目标
- 集成 springdoc-openapi 并开放 OpenAPI JSON 与 Swagger UI
- 为接口补充用途、参数、响应示例和 Bearer Token 鉴权说明
- 使用自动化检查避免接口实现与文档长期偏离
集成 springdoc-openapi
Spring Boot 3 使用 Jakarta 命名空间,应选择 springdoc-openapi 2.x 系列。下面示例把版本集中在属性中,实际项目应替换为团队验证过的 2.x 版本,并由依赖更新流程统一维护。
<properties>
<java.version>21</java.version>
<springdoc.version>2.8.0</springdoc.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>${springdoc.version}</version>
</dependency>
</dependencies>依赖生效后,springdoc 会扫描 Spring MVC 控制器、请求模型和响应模型,生成 OpenAPI JSON,并提供 Swagger UI。若项目使用 WebFlux,应改用对应的 WebFlux starter。

配置文档入口与基础信息
集中配置文档路径可以避免环境间地址不一致。生产环境是否开放 Swagger UI 应由安全策略决定,但 OpenAPI JSON 通常仍可在受控网络内提供给网关、测试平台或代码生成工具。
springdoc:
api-docs:
path: /openapi
swagger-ui:
path: /docs
operations-sorter: method
tags-sorter: alpha
packages-to-scan: com.example.user.api
server:
port: 8080配置生效后,机器契约位于 /openapi,交互页面位于 /docs。packages-to-scan 应只覆盖对外接口包,避免把内部控制器误暴露到文档中。
补充接口描述与示例
下面示例为创建用户接口补充摘要、请求说明、状态码和示例。接口返回统一响应对象时,也应在文档中明确业务数据位于哪个字段,避免调用方只能依赖猜测。
package com.example.user.api;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.ExampleObject;
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 jakarta.validation.Valid;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.*;
@Tag(name = "用户管理", description = "创建和查询用户")
@RestController
@RequestMapping("/api/users")
public class UserController {
@Operation(
summary = "创建用户",
description = "邮箱必须唯一,成功后返回新用户编号"
)
@ApiResponses({
@ApiResponse(responseCode = "201", description = "创建成功"),
@ApiResponse(
responseCode = "400",
description = "请求参数不合法",
content = @Content(examples = @ExampleObject(
value = "{\"code\":\"VALIDATION_ERROR\",\"message\":\"email 格式不正确\"}"
))
)
})
@PostMapping
@ResponseStatus(HttpStatus.CREATED)
public UserResponse create(@Valid @RequestBody CreateUserRequest request) {
return new UserResponse(1001L, request.name(), request.email());
}
public record CreateUserRequest(
@NotBlank String name,
@Email String email
) {}
public record UserResponse(long id, String name, String email) {}
}这段代码可直接放入已启用 Spring MVC 的项目。验证注解负责运行时校验,OpenAPI 注解负责补充业务语义;两者职责不同,不应只写其中一类。
声明 Bearer Token 鉴权
鉴权方案应在全局声明,再在需要保护的接口或控制器上引用。这样 Swagger UI 才会显示授权入口,生成的客户端也能识别 Authorization: Bearer <token>。
package com.example.config;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.enums.SecuritySchemeType;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.security.SecurityScheme;
import org.springframework.context.annotation.Configuration;
@Configuration
@OpenAPIDefinition(
info = @Info(
title = "用户服务 API",
version = "v1",
description = "用户服务对外接口契约"
),
security = @SecurityRequirement(name = "bearerAuth")
)
@SecurityScheme(
name = "bearerAuth",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "JWT"
)
public class OpenApiConfig {
}若只有部分接口需要登录,不要在 @OpenAPIDefinition 中全局声明,应把 @SecurityRequirement(name = "bearerAuth") 放到受保护的控制器或方法上,公开接口则保持无鉴权要求。
运行并验证文档
启动应用后先检查 JSON 契约,再检查 Swagger UI。JSON 更适合自动化校验,UI 更适合人工查看描述和示例。
mvn spring-boot:run预期输出
Started <APPLICATION> in <TIME> seconds实际应用名和启动耗时会不同。随后访问 http://localhost:8080/openapi,应得到包含 openapi、info、paths 和 components 的 JSON;访问 http://localhost:8080/docs,应看到“用户管理”分组和“创建用户”接口。
可在持续集成中启动测试环境并保存 /openapi 结果,与仓库中的基线契约比较。新增必填字段、删除响应字段或修改状态码都可能造成破坏性变更,应由评审确认,而不是只依赖 Swagger UI 能否打开。