中间件：SpringDoc OpenAPI（API 文档 / Swagger UI）

1. 简介

SpringDoc OpenAPI 在本项目中用于自动生成并可视化展示后端 REST API 文档。它在运行时扫描所有 @RestController，生成符合 OpenAPI 3 规范的文档，并提供 Swagger UI 交互界面，方便前端对接与接口调试。项目使用 springdoc-openapi-starter-webmvc-ui 2.8.17。

2. 引入方式

pom.xml 引入：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>${springdoc.version}</version>   <!-- 2.8.17 -->
</dependency>

3. 配置位置

application.yml 中的 springdoc 段：

springdoc:
  api-docs:
    path: /v3/api-docs        # OpenAPI JSON 文档路径
  swagger-ui:
    path: /swagger-ui.html    # Swagger UI 页面路径

4. 在哪里应用

• 自动文档生成：无需额外注解，框架自动扫描 controller/*Controller.java 下所有 @RestController、@RequestMapping、@GetMapping、@PostMapping 等接口，结合 DTO（dto/*）生成请求/响应结构。
• 鉴权放行：security/BearerSessionFilter.java 的 shouldNotFilter 白名单中放行了 /v3/api-docs 与 /swagger-ui、/swagger-ui.html，使文档与 UI 访问无需 Bearer 令牌。

@Override
protected boolean shouldNotFilter(HttpServletRequest request) {
    String path = request.getRequestURI();
    return "OPTIONS".equalsIgnoreCase(request.getMethod())
        || path.equals("/api/health")
        || path.equals("/api/auth/login")
        || path.equals("/api/auth/register")
        || path.startsWith("/v3/api-docs")
        || path.startsWith("/swagger-ui")
        || path.equals("/swagger-ui.html");
}

5. 怎么应用（示例）

启动后端后，直接通过浏览器访问：

• Swagger UI 交互界面：http://localhost:8080/swagger-ui.html
• OpenAPI JSON 文档：http://localhost:8080/v3/api-docs

在 Swagger UI 中可查看每个接口的入参、响应模型，并可直接「Try it out」发起请求调试（需先调用登录接口获取 Bearer 令牌，再在界面顶部 Authorize 中填入）。

6. 作用是什么

• 接口文档自动化：代码即文档，接口变更后文档自动同步，避免手工维护文档过期。
• 前后端协作：为前端提供可交互的接口说明与调试入口，降低联调成本。
• 可视化调试：内置 Swagger UI 可作为轻量级 API 测试工具，无需额外 Postman 配置。

7. 相关文件清单

• pom.xml（springdoc-openapi-starter-webmvc-ui）
• src/main/resources/application.yml（springdoc）
• src/main/java/com/yang/backend/security/BearerSessionFilter.java（文档路径白名单）
• src/main/java/com/yang/backend/controller/*Controller.java（被扫描生成文档）
• src/main/java/com/yang/backend/dto/*（请求/响应模型）