API 文档使用指南

接入 OpenAPI 与 Scalar，核对展示开关和安全链。

3.0.0-SNAPSHOT网站同步 2026-09-20

本文约定 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；编译目标和环境前提见环境准备。先配置本地 JAVA_HOME 与 Maven PATH，在最窄的 ineed-dev reactor 中运行双栈兼容测试：

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 且不含预填凭据。