# API 文档使用指南

本文约定 MVC 与 WebFlux 应用统一的 API 文档生成与展示策略。

版本说明（2026-09-19）：下文 Scalar + springdoc API starter 是本地工作树正在采用的目标配置。此次文档提交不包含配套 Java/POM 修改；其基线代码 `95a72d03` 仍保留 Swagger UI starter 与兼容路径。在代码迁移独立完成并验证之前，不能仅凭本页认定 Swagger UI 已从制品移除，也不能提前移除已有兼容约束。

基线兼容约束：由 `Phase53.4` 在 v1.9 closeout 或 2026-10-31（取较早者）发起复查，到期不自动删除。移除前需确认仓库、脚本和已知消费者没有活跃 Swagger UI 引用，Scalar 替代入口可用，并通过 MVC/WebFlux 文档路径回归；owner 与证据记录在所属规划工作区的 `.planning/phases/53.4-api/53.4-swagger-compatibility.json`。

## 入口与职责

| 能力 | 路径 | 状态 | 职责 |
|------|------|------|------|
| Scalar | `/scalar` | 主入口 | 读取本应用的 OpenAPI 文档并提供统一展示界面 |
| springdoc | `/v3/api-docs` | 唯一生成底座 | 从当前应用的控制器和注解生成 OpenAPI JSON |

Scalar 必须把 `url` 固定为本地 `/v3/api-docs`。不得配置远程规范地址，不得预填用户名、密码、令牌、API key 或 OAuth secret。开发启动器同时关闭 Scalar Agent 和 Test Request 按钮，避免浏览器侧代理或带凭据请求成为默认能力。

springdoc 是唯一 OpenAPI 生成底座，项目只引入其 API starter。Scalar 消费 springdoc 的输出，不引入 Swagger UI 或第二套规范生成与注解体系。

## 分组约定

- 默认未分组文档使用 `/v3/api-docs`，Scalar 主入口也固定读取该地址。
- 只有应用确实需要隔离不同消费方或 API 面时才新增 springdoc group；group 名称必须稳定、体现业务边界，并在应用文档中记录对应的 `/v3/api-docs/{group}` 地址。
- 不要为 MVC 与 WebFlux 创建语义不同的默认 group。相同业务面应使用相同命名。

## 鉴权约定

- 文档页面是否需要登录由应用安全策略决定，不能通过在 Scalar 配置中写入固定凭据来绕过鉴权。
- OpenAPI security scheme 只描述客户端应如何认证；真实 token、API key、密码和 OAuth secret 不得进入 source YAML、OpenAPI 示例或文档仓库。
- 需要调试受保护接口时，由开发者在受控客户端中显式提供短期凭据。Scalar 的 Test Request 功能在开发启动器中保持关闭。

## 验证

本轮开发验证使用 JDK 25、Maven 3.9.15；编译目标和环境前提见[环境准备](../getting-started/prerequisites.md)。先配置本地 `JAVA_HOME` 与 Maven PATH，在最窄的 ineed-dev reactor 中运行双栈兼容测试：

```bash
mvn \
  -f "${INEED_JAVA_ROOT:?set as described in prerequisites}/ineed-projects/ineed-dev/pom.xml" \
  -pl ineed-dev-webmvc-jpa-bootstrap,ineed-dev-webflux-r2dbc-bootstrap \
  -am \
  -Dtest=WebMvcApiDocumentationCompatibilityTest,WebFluxApiDocumentationCompatibilityTest \
  -Dsurefire.failIfNoSpecifiedTests=false \
  test
```

测试必须同时确认 `/scalar` 返回引用本地 `/v3/api-docs` 的 HTML、`/v3/api-docs` 返回 OpenAPI JSON，并扫描四个开发启动器的 Scalar 配置一致、显式开启 `application.show-api-doc` 且不含预填凭据。