接口文档：springdoc-openapi 生成 OpenAPI/Swagger UI

对外接口要给人（前端、合作方）看，手写文档必然过期。springdoc-openapi 是社区主流方案（非 Spring 官方）：启动时自动扫描 Controller 生成符合 OpenAPI 3 的描述文件，并提供 Swagger UI 交互页面，代码即文档。

引入依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.8.11</version>   <!-- Boot 3.x 用 2.8.x；Boot 4 需 v3.0.x，版本矩阵以 springdoc 官方文档为准 -->
</dependency>

WebFlux 工程换成 springdoc-openapi-starter-webflux-ui。启动后访问：

• http://localhost:8080/swagger-ui.html（或 /swagger-ui/index.html）——交互式 UI；
• http://localhost:8080/v3/api-docs —— OpenAPI JSON。

注解驱动文档

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理", description = "用户增删改查接口")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "按 ID 查询用户", description = "返回单个用户")
    public UserDto get(@Parameter(description = "用户 ID") @PathVariable Long id) {
        return userService.findById(id);
    }

    @PostMapping
    @Operation(summary = "新建用户")
    @ApiResponse(responseCode = "201", description = "创建成功")
    @ApiResponse(responseCode = "400", description = "参数校验失败")
    public UserDto create(@Valid @RequestBody UserCreateRequest req) {
        return userService.create(req);
    }
}

DTO 上可用 @Schema(description = "...", example = "...") 描述字段，让示例更友好；方法返回体、请求体都会自动按 Jackson 序列化结果建模。

接入 JWT 鉴权（配合第 31 章）

声明安全方案，UI 上会出现 Authorize 按钮：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
            .info(new Info().title("示例平台 API").version("v1")
                .description("示例文档，仅演示用"))
            .components(new Components().addSecuritySchemes("bearerJwt",
                new SecurityScheme().type(SecurityScheme.Type.HTTP)
                    .scheme("bearer").bearerFormat("JWT")));
    }
}

Controller 类或方法上加 @SecurityRequirement(name = "bearerJwt")，点击 Authorize 粘贴令牌后，UI 调试请求会自动带 Authorization: Bearer xxx。

常用配置与生产提示

springdoc:
  api-docs:
    path: /v3/api-docs      # 默认路径
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: method

• 多分组场景可用 GroupedOpenApi Bean 按包名/路径拆分文档；
• 生产环境若不想暴露文档，置 springdoc.api-docs.enabled=false（或交给 Spring Security 保护该路径）；
• 生成代码的注解属 springdoc 对 OpenAPI 规范的封装，行为以官方文档为准。

小结：引入 starter-webmvc-ui 即可自动出 OpenAPI；用 @Tag/@Operation/@Schema 补语义、@SecurityRequirement 接 JWT，文档随代码演进，永不手写过期。