api-documentation

API 文档

当主要工作是发布或更新面向开发者的 API 文档，帮助集成者快速取得初步成功、了解真实的参考信息，并在 API 演进过程中顺利推进时，使用此技能。

api-documentation 是文档技能组的核心，适用于：

• 端点／架构参考文档
• 快速入门和首次成功流程
• 面向任务的集成指南
• SDK 指南
• Webhook 传递／验证文档
• 开发者门户导航和分组参考页面
• 与文档页面相关的迁移更新

在选择模式或输出方案前，请先阅读以下支持文档：

• references/documentation-modes-and-boundaries.md
• references/output-packets-and-navigation.md
• references/example-and-reference-checklist.md
• references/publishing-and-drift-control.md

何时使用此技能

• 团队需要 API 参考文档、快速入门或门户页面，供外部开发者、合作伙伴或内部集成者实际使用。
• OpenAPI 或架构文件已存在，但文档仍需补充结构、示例、身份验证／设置指南、错误处理或更清晰的导航。
• 身份验证、版本控制、重试、分页、Webhook 或 SDK 发生变更后，现有 API 文档已过时。
• 公共、合作伙伴或内部 API 发布需要面向开发者的指南、迁移说明或可信示例。
• API 范围较大，需要分组、选择性发布或更清晰的门户结构，而非堆成一份庞大的参考文档。

何时不使用此技能

• 主要工作是设计资源、端点形态、架构规则或版本控制策略 → 使用 api-design。
• 主要工作是编写内部规范、ADR、运维手册、发布文档或系统迁移流程 → 使用 technical-writing。
• 主要工作是面向最终用户的产品 UI 引导、截图、教程或帮助中心文档 → 使用 technical-writing。
• 主要工作是实现身份验证／会话／提供方行为，而非记录 API 使用者如何进行身份验证 → 使用 authentication-setup。
• 主要工作是维护发行说明、semver 或变更日志 → 使用 changelog-maintenance。
• 尚无可信的 API 行为事实来源 → 将未解决的契约问题交回 api-design，而不是凭感觉编造文档。

说明

第 1 步：对 API 文档工作分类

起草前先规范请求。

api_documentation_mode:
  primary_mode: reference | quickstart | task-guide | sdk-guide | webhook-guide | migration-update
  api_style: rest | graphql | webhook | sdk | mixed | unknown
  audience: external-developers | internal-integrators | partners | mixed | unknown
  source_of_truth: openapi | graphql-schema | code-annotations | tests | mixed | unknown
  docs_surface: developer-portal | docs-site | repo-markdown | sdk-site | internal-catalog | unknown
  navigation_scope: single-operation | grouped-resource | large-api-surface | portal-section | unknown
  maintenance_state: new-docs | refresh | drift-fix | launch-critical

每次运行选择一种主要模式：

• reference → 端点／架构事实，包括参数、字段、错误、限制和示例
• quickstart → 以最快方式完成首次成功的 API 调用或 Webhook 接收
• task-guide → 实现一项工作流或集成目标
• sdk-guide → 语言／客户端库指南，以及示例和注意事项
• webhook-guide → 传递、验证、重试和本地调试指南
• migration-update → 文档页面上的行为变更及迁移路径

如果文档页面范围较大，还要判断任务是否同样涉及分组／导航。不要把大型页面的信息架构问题藏在泛泛的“编写文档”请求中。

步骤 2：确认技能边界和实际开发者任务

撰写前，请回答以下四个问题：

1. 谁会集成此 API？阅读文档后，他们应完成什么具体任务？
2. 当前作为真实契约唯一可信来源的制品是什么？
3. 你要更新哪个文档展示面：门户、仓库文档、SDK 网站、内部目录，还是多个展示面？
4. 哪些相邻技能必须排除在范围之外？

快速分流表：

如果请求听起来像……	使用
“在编码前设计端点／资源／架构”	api-design
“撰写架构文档／ADR／发布计划／运行手册”	technical-writing
“撰写介绍如何使用产品 UI 的客户帮助文档”	technical-writing
“解释提供方设置／会话中间件／令牌实现”	authentication-setup
“总结此次发布包含的内容”	changelog-maintenance
“撰写开发者门户／OpenAPI 文档／快速入门／Webhook 指南”	api-documentation

步骤 3：收集最少但可信的证据

不要只凭过时的规范撰写 API 文档。先收集最少量的可信证据：

• 当前的 OpenAPI／GraphQL 架构／端点列表／SDK 接口
• 身份验证要求：密钥、标头、作用域、签名、沙盒与生产环境的区别、回调／Webhook 验证
• 符合当前行为的请求和响应示例
• 常见错误、重试、限制、分页／游标行为以及幂等性预期
• 版本控制、弃用和迁移说明
• 能确保示例准确的测试、固定数据或已验证请求
• 发布限制：门户导航、选择性发布需求、文档站点结构或内部目录分组

如果细节不完整，请明确标注假设，并列出文档缺口，不要假装确定。

步骤 4：选择最小且实用的文档组合

根据开发者任务选择输出。默认情况下，不要把快速入门、参考文档、SDK 文档和迁移说明全部塞进一个超长页面。

常见的文档组合：

• 一个快速入门页面
• 一个分组后的参考文档部分
• 一个任务／集成指南
• 一个 SDK 指南
• 一个 Webhook 指南
• 一篇迁移更新说明
• 一份文档缺口／偏差检查清单，用于记录尚未解决的真实信息来源问题
• 针对大型 API 接口集的一份导航／分组提案

有关模式结构和门户／分组指南，请使用 references/output-packets-and-navigation.md。

步骤 5：遵循 API 文档规则，而非通用写作建议

严格遵循以下规则：

• 从开发者任务和集成接口切入，不要写营销文案。
• 尽早说明身份验证和环境假设。
• 确保示例准确：优先使用测试、已验证请求或真实固定数据结构。
• 说明实际运行情况：错误、重试、限制、分页、Webhook 重放、最终一致性、幂等性。
• 区分参考文档中的事实与工作流指导。
• 明确大型 API 的导航决策：分组、选择性发布和相关指南链接都很重要。
• 有目的地链接到其他文档：快速入门链接到更深入的参考文档；参考文档链接到任务指南；迁移更新链接到变更日志／发布说明，而不是取而代之。

步骤 6：主动防止文档偏差

最终确定前，记录：

• 契约真实信息来源
• 示例真实信息来源
• 发布展示面
• 审核触发条件
• 易产生偏差的部分：身份验证、限制、重试、版本控制、Webhook 字段、SDK 示例、迁移说明
• 必须保持一致的配套文档：快速入门、SDK 页面、变更日志条目、Postman 集合、门户导航

请使用 references/publishing-and-drift-control.md 作为防止偏差的检查清单。

第 7 步：验证输出质量

发布前，检查：

1. 新集成者能否借助这套文档顺利完成首次调用？
2. 身份验证和环境方面的前提是否在首次调用前清晰说明？
3. 示例是否与实际行为一致？
4. 在需要的地方，是否说明了错误、限制、重试、分页或验证注意事项？
5. 输出内容是否足够精简，能满足请求？
6. 指向 api-design、technical-writing、technical-writing、authentication-setup 和 changelog-maintenance 的后续引导是否仍然明确？

示例

示例 1：合作伙伴 API 快速入门

输入：“为我们的 Orders API 编写快速入门指南，让合作伙伴能够创建 API 密钥、发送第一个 POST /orders 请求，并验证返回的订单 ID。”

**理想输出形式：**选择 quickstart，尽早说明前提条件和身份验证，提供一个能成功完成首次调用的请求及成功检查，并链接到更详尽的参考资料。

示例 2：整理大型参考文档

输入：“我们的开发者门户发布了一个庞大的 OpenAPI 集合；请帮我们重新归类端点，仅展示适合合作伙伴的部分，并添加便于开发者浏览的导航。”

**理想输出形式：**将其视为 reference 加上 navigation/grouping 工作，提出分组章节或选择性发布方案，保留准确的参考链接，并且不声称仅靠自动生成就能解决结构问题。

示例 3：Webhook 变更通知

输入：“更新我们的 webhook 文档：invoice.paid 现在会重试 24 小时，包含 attempt_count，并且每次投递都需要进行 HMAC 验证。”

**理想输出形式：**选择 webhook-guide 或 migration-update，记录重试和验证行为，更新受影响的示例，并将实现细节和发布说明规范排除在范围之外。

示例 4：引导至 API 设计

输入：“我们尚未决定应该使用 REST 还是 GraphQL，并且需要资源模型和分页方案。”

**理想输出形式：**将任务引导至 api-design，说明文档发布前必须先完成契约／接口设计，并可注明后续需要哪些文档内容。

最佳实践

1. 将 API 文档视为开发者工作流中的产物，而不只是架构渲染结果。
2. 将契约设计与面向开发者的发布分开。
3. 优先采用小而准确的内容包，而不是一个巨大的门户页面。
4. 尽早明确说明身份验证、示例、限制、重试、分页和 webhook 行为。
5. 对于大型内容，记录导航／分组决策，而不是将其埋在正文中。
6. 将文档维护与真实可信的信息源关联起来，避免更新时出现偏差。
7. 将相关的写作、身份验证实现和发布规范任务引导至合适的相邻技能。

参考资料

• OpenAPI Initiative
• Stripe API 参考
• GitHub REST API 文档
• ReadMe 指南
• Redocly 文档
• Postman API 文档