Hyperswitch API 参考文档生成机制：从 Rust 代码到 OpenAPI 规范再到 Mintlify 渲染的完整工作流

Hyperswitch 的 api-reference 目录是整个项目 API 文档的“源头”：OpenAPI 规范文件直接由代码库生成，再由 Mintlify 渲染成可交互的在线文档。本篇指南基于 api-reference/README.md 的完整操作流程，结合 crates/openapi 源码，讲清楚三件事：如何重新生成 openapi_spec_v1.json 这类规范文件、如何在本地渲染并预览整套 API 文档、以及新增路由后如何让它在文档站点上显示出来。读完后你可以独立完成 Hyperswitch API 文档的本地构建与更新。

api-reference 目录结构与文档组织

api-reference 目录同时承担两个角色：一是存放 OpenAPI 规范文件（机器可读的接口契约），二是存放 Mintlify 文档页面的 Markdown/MDX 源码（人读的渲染结果）。关键内容包括：

• docs.json：Mintlify 站点的导航与主题配置文件。它定义了三个文档 Tab（Documentation、Locker API Reference、Decision Engine API Reference），并在 api.openapi 字段中列出四份规范文件：v1/openapi_spec_v1.json、v2/openapi_spec_v2.json、rust_locker_open_api_spec.yml 和 decision_engine_openapi-specs.json。Mintlify 会自动根据这些 OpenAPI 文件为每个端点生成页面。
• v1/openapi_spec_v1.json 与 v2/openapi_spec_v2.json：由代码库自动生成的两版 API 规范，是本文档工作流的核心产物。
• v1/、v2/ 子目录：由 Mintlify 抓取工具从规范文件中批量生成的路由级 MDX 页面，按实体（payments、refunds、customers、routing 等）分目录组织，每个端点对应一个 -- 分隔的页面文件，例如 v1/payments/payments--create.mdx。
• essentials/：认证、错误码、限流等横切主题文档；introduction.mdx 是文档站的入口页。

值得注意的是，docs.json 的 navigation 中按 1.0.0 和 2.0.0 [BETA] 两个版本分别组织了页面分组，并且部分 V1 页面（如 Customers、Payment Methods）被明确归入 "Deprecated APIs" 分组——这体现了文档导航与 API 版本演进之间的对应关系。

生成 OpenAPI 规范文件

规范文件的产生有两条路径，两者最终写入同一组文件：

1. CI 自动生成：每次 PR 提交时，CI 流水线会自动重新生成 OpenAPI 文件并保证它与代码保持一致，开发者通常不需要手动执行；
2. 本地手动生成：运行 README 给出的命令：

cargo r -p openapi --features v1

命令背后的实现

该命令对应工作区中的 crates/openapi 包，其入口 crates/openapi/src/main.rs 的逻辑非常清晰：

• v1 与 v2 是两个互斥的 cargo feature。main() 开头用 compile_error! 显式禁止同时启用两个 feature，防止两个版本的规范互相覆盖；crates/openapi/Cargo.toml 中可以看到 feature 到下游 crate 的映射：v1 启用 api_models/v1 与 common_utils/v1，v2 启用 api_models/v2、common_utils/v2 以及 api_models/tokenization_v2。
• 根据启用的 feature，程序从 utoipa::OpenApi trait 取出对应版本的结构体（openapi::ApiDoc 或 openapi_v2::ApiDoc），调用 to_pretty_json() 序列化为格式化的 JSON，并写入工作区根目录下的 api-reference/v1/openapi_spec_v1.json 或 api-reference/v2/openapi_spec_v2.json（路径由 router_env::workspace_path() 定位到仓库根目录后拼接）。
• 生成完成后打印 Successfully saved OpenAPI specification file at '...' 作为成功提示；如果两个 feature 都没启用，则打印提示要求启用 v1 或 v2。
• 一个值得注意的细节：v1 路径下生成后还会二次处理文件内容，在第 3 行插入 "x-mcp": { "enabled": true } 扩展字段（见 main.rs），用于在规范中开启 MCP 相关能力。

因此，如果你只关心 V2 规范的本地重新生成，把命令中的 feature 换成 v2 即可：

cargo r -p openapi --features v2

规范内容从哪里来

ApiDoc 定义在 crates/openapi/src/openapi.rs，通过 #[derive(utoipa::OpenApi)] 宏一次性声明了整份规范：

• info(...)：标题、联系信息以及一大段 Markdown 描述（含 Base URL 表格与 api-key / publishable key 的认证说明）；
• servers(...)：以 sandbox 环境为默认服务器；
• tags(...)：按业务实体声明的 16 个标签（Merchant Account、Payments、Refunds、Mandates、Customers、Disputes、Routing 等），决定了文档页面上端点的分组方式；
• paths(...)：按注册顺序列出约两百个端点的路由函数（routes::payments::payments_create、routes::refunds::refunds_create 等）。源码注释明确说明“The paths will be displayed in the same order as they are registered here”，即端点在文档中的顺序由这里的注册顺序决定；
• components(schemas(...))：登记了上千个请求/响应/枚举类型的 JSON Schema，来自 api_models、common_types、common_utils、euclid 等 crate——这也是为什么规范文件体积极大的原因；
• modifiers(&SecurityAddon)：通过实现 utoipa::Modify 的 SecurityAddon 向 components.securitySchemes 注入五套鉴权方案——api_key（商户服务端密钥）、admin_api_key（管理端特权操作）、publishable_key（前端可用）、ephemeral_key（临时单资源访问）和 jwt_key（Bearer JWT）。

端点的具体文档元数据（HTTP 方法、路径、参数、响应示例）则分散在 crates/openapi/src/routes/ 下的 28 个路由模块中（payments.rs、refunds.rs、routing.rs、payouts.rs 等，清单见 routes.rs），每个模块为对应实体的端点提供 utoipa 的 ToSchema/path! 描述。

本地渲染 OpenAPI 规范文件

要预览最终文档站，需要在本地运行 Mintlify 开发服务器。README 给出的操作步骤是：

1. 安装 Mintlify CLI（其本地开发设置参考 Mintlify 官方文档）；
2. 进入 docs.json 所在的目录：

cd api-reference

3. 启动本地开发服务：

mint dev

启动后 Mintlify 会读取 docs.json，把四份 OpenAPI 规范展开为可交互的端点文档（含参数表格、请求/响应示例），并与其他 MDX 页面一起按 Tab/Group 组织展示。这也是开发者在改动 API 后最快验证文档呈现效果的方式。

新增路由后刷新文档页面

当你在代码中新增了端点、并重新生成规范文件后，这些新端点还不会自动出现在文档站的导航里。README 给出的完整流程是：

1. 先切到规范文件所在目录：

cd api-reference

2. 运行 Mintlify 的 OpenAPI 抓取命令，从规范文件中生成路由级页面文件：

npx @mintlify/scraping@latest openapi-file v1/openapi_spec_v1.json -o v1

该命令会为规范中的每个端点在 api-reference/v1/ 下生成对应的 MDX 文件（如 v1/payments/payments--create.mdx 这种 实体--操作 命名风格的页面）。

3. 把新生成的路由文件登记到导航配置中：在 docs.json（README 写作时称 mint.json，当前仓库已演进为 docs.json）的 navigation 节点下，将新页面按所属分组添加到对应实体的 pages 数组里。例如新增一个 payments 端点，就应加到 "Payments Core APIs" → "Payments" 分组的页面列表中。

版本提示：README 末尾特别注明，处理 V2 API 参考时，把上述命令中所有 v1 替换为 v2 即可，即抓取 v2/openapi_spec_v2.json 并输出到 v2 目录。

V1 与 V2 文档的双轨组织

从 docs.json 的导航结构可以确认，同一套文档站并行维护两个 API 版本：

• V1（1.0.0）：完整的 Payments Core APIs（Payments、Refunds、Disputes、Payouts、Authentication 等）+ Account management APIs（Organization、Merchant Account、Business Profile、API Key、MCA、GSM）+ Other APIs（Event、Poll、Blocklist、Routing、Relay、Schemas、Subscriptions），另有独立的 "Deprecated APIs" 分组沉淀 V1 旧版 Customers、Payment Methods、Mandates 端点。
• V2（2.0.0 [BETA]）：以更简洁的意图模型为主，包含 Payments（create-intent / confirm-intent / session-token 等 10 个端点）、Payment Methods、Network Tokenization、Customers、Refunds，以及 Profile、Connector Account、Routing、Proxy、Tokenization、Revenue Recovery 等管理端端点。

两版共用 introduction 与 essentials 等基础页面（V2 的 Essentials 不包含 authentication 页，可从其分组配置看出差异）。另外，V1 导航中部分 "Payment Methods"、"Customers" 页面实际指向 v2/...--v1 命名的文件（例如 v2/payment-methods/payment-method--create-v1），说明 V1 API 的文档页面已经部分复用 V2 目录下的抓取产物，维护时需注意这类跨版本引用。

小结：推荐的文档维护路径

结合 README 与源码结构，一次典型的“新增 API 端点 → 文档上线”流程如下：

1. 在 crates/openapi/src/routes/ 对应模块中为新端点补充 utoipa 路由描述，并注册到 openapi.rs 的 paths(...) 中（顺序即文档展示顺序）；
2. 本地运行 cargo r -p openapi --features v1（V2 则换 v2）重新生成 openapi_spec_v1.json，确认新端点与 Schema 已出现在规范文件中；
3. 运行 npx @mintlify/scraping@latest openapi-file v1/openapi_spec_v1.json -o v1 生成路由 MDX 页面；
4. 在 docs.json 的 navigation 对应分组中登记新页面；
5. cd api-reference && mint dev 本地预览，确认无误后提交 PR，CI 会在合并前再次自动重新生成规范文件，保证仓库内 JSON 与代码始终一致。

这条“代码即文档”的链路（Rust 类型系统 → utoipa 派生 → JSON 规范 → Mintlify 抓取与渲染）是 Hyperswitch API 参考文档与实现保持同步的关键机制，也是其文档可被机器（如 Agent、LLM）直接消费的基础——规范文件本身就是结构化的接口契约。