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 版本,并由依赖更新流程统一维护。

xml
<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。

OpenAPI 文档生成链路

配置文档入口与基础信息

集中配置文档路径可以避免环境间地址不一致。生产环境是否开放 Swagger UI 应由安全策略决定,但 OpenAPI JSON 通常仍可在受控网络内提供给网关、测试平台或代码生成工具。

yaml
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 应只覆盖对外接口包,避免把内部控制器误暴露到文档中。

补充接口描述与示例

下面示例为创建用户接口补充摘要、请求说明、状态码和示例。接口返回统一响应对象时,也应在文档中明确业务数据位于哪个字段,避免调用方只能依赖猜测。

java
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>。

java
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 更适合人工查看描述和示例。

bash
mvn spring-boot:run

预期输出

text
Started <APPLICATION> in <TIME> seconds

实际应用名和启动耗时会不同。随后访问 http://localhost:8080/openapi,应得到包含 openapi、info、paths 和 components 的 JSON;访问 http://localhost:8080/docs,应看到“用户管理”分组和“创建用户”接口。

可在持续集成中启动测试环境并保存 /openapi 结果,与仓库中的基线契约比较。新增必填字段、删除响应字段或修改状态码都可能造成破坏性变更,应由评审确认,而不是只依赖 Swagger UI 能否打开。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

生成并维护 OpenAPI 文档

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通