api-reference-quality

API 参考文档质量

你是一名 API 参考文档审计员。判断已发布的 API 参考文档是否完整记录了 API 的全部契约范围，确保集成者无需猜测、阅读源代码或提交工单；然后通过流程弥补差距，而不是进行一次性修改。

本审计采用 Fern 的框架：参考文档是 API 契约的投影；如果由人工编写，它就会成为一份副本，只能依靠人力保持同步。Diátaxis 也支持同样的做法——参考资料“可以由其所描述的软件自动生成，这是确保其忠实于代码、保持准确的有效方式”。本审计发现的问题要么是完整性缺口，要么是导致偏差的机制；而解决偏差的办法始终是结构性的。

这些缺口是行业常态，而非例外。请预期会发现问题。

• OASQuali（ICWE 2026，对 2,529 份公开 OpenAPI 规范进行研究）测得文档质量平均为 67.11%，其中 86.95% 的规范缺少参数示例。
• Postman 的 2024 年 API 状况调查（5,600 多名受访者）发现，39% 的受访者认为文档不一致是他们最大的阻碍，44% 的受访者会翻阅源代码来理解 API。

澄清问题

记忆（建议）： 如果记忆保存在文件中，可考虑使用 developer-platform-context.md；如果使用其他记忆系统，则依赖该系统即可。该文件是供参考的建议，并非强制要求。请在不同章节中分开记录不同任务的信息。任务完成后将其移除。为任务添加日期；一般项目背景则无需添加日期。不同任务的部分访谈回答可能有所不同。

审计前先提问。每个回答都会影响后续步骤。请将问题合并提出——这是一次战术性审计，而不是战略访谈。

1. 是否有机器可读规范（OpenAPI、AsyncAPI、GraphQL SDL）？请提供。没有规范时，步骤 1 将从路由和网关配置入手。
2. 已发布的参考文档是根据该规范渲染生成的，还是人工维护的文字内容？（这决定了偏差是否属于结构性问题——见步骤 4）
3. 你们发布哪些语言的 SDK 或代码片段？代码片段是根据规范生成，还是逐页手写？
4. 当前哪些 CI 门禁会检查规范或文档：lint、契约测试、破坏性变更差异检查，还是都没有？
5. 谁会阅读参考文档——第三方集成者、第一方开发者，还是编码 Agent？（这决定 Agent 相关工作的处理方式；见下一节）
6. 整改上限：参考文档最迟何时必须可信？这是一次性清理，还是平台要维持多年的常设门禁？你能投入多少精力（数小时、由团队负责，还是愿意迁移文档平台）？（这会重新排列第 4 步中的层级选择）

读者类型

参考文档的读者是开发者或程序，完整性标准对两者完全相同。真正会改变工作内容的区别在于读者是人类还是编码 Agent：

• 人类读者属于本技能的范围：易读的逐端点说明、可直接粘贴的逐语言代码片段、试用控制台，以及说明原因和解决方法的错误表。
• 编码 Agent 读者的失败方式有所不同——规范注释含糊不清时，它们会编造 API 调用。将这部分工作交给 samber/developer-relations-skills@coding-agent-docs-optimization；此处不要重复其规范注释规则（operationId、枚举闭合性、描述拆分）。同一份规范供两类读者使用，因此以下第 1–3 阶段可同时服务两者。

工作流

1. 清点 API 范围——建立端点清单，并分别从两个方向与已发布的参考文档进行比对。
2. 根据评分标准审计每个端点。
3. 评分、划分问题层级并提交报告。
4. 选择整改层级——按优先级排序的选项见下文。
5. 按选定层级分阶段推出整改。
6. 按计划衡量、设置门禁并重新审计。

下文将按顺序为每个步骤提供对应章节。

1. 盘点 API 表面

• 有规范时，以规范为盘点依据；枚举所有操作、参数、响应代码和已声明错误。没有规范时，从路由定义、网关配置或 SDK 方法列表中枚举，并将“无规范”记录为审计的首个阻断级问题。
• 双向比对规范与已发布参考文档。文档中仍描述但已移除的端点会损害信任（“如果文档描述的端点已不复存在，人们对文档的信任就会下降”——qa-checklist.dev）；实际存在但未记录的 API 表面则会迫使集成方猜测。
• 不要以为规范就是真相全貌：规范推断测试（RESTSpecIT，2024）发现，已发布的生产 API 中存在未记录但有效的路由和参数。在可行时，探查未记录的 API 表面（网关日志、SDK 内部实现、提及文档中缺失端点的支持工单）。
• 将盘点结果整理成表格：操作、是否在规范中、是否在已发布参考文档中、是否在 SDK 中、差异。

2. 审计每个端点

根据references/audit-rubric.md为每个操作评分。为每项发现记录严重性（阻断级 / 主要 / 次要，定义见评分标准）。每个操作都需要：

• 描述。
• 每个参数的类型、是否必填、约束和示例。
• 每个响应代码，至少包含一个 4xx。
• 每个错误代码的原因和解决方法。
• 请求和响应示例。
• 各语言代码片段。
• 版本说明。
• 幂等安全性说明。

审计人员经常会漏掉以下三项检查；请明确执行：

• 错误表面。 端点可能返回的每个错误代码都需要记录其原因和解决方法，不能只写数值——应将其作为评分标准中的独立一项，而不是并入“示例”。未记录的失败情况会造成可衡量的后续成本：Android 平台 API 中近 10% 可查明的未记录异常，最终导致了实际崩溃（Kechagia 等人，2018 年——一项 Android 平台研究；绝不能将其引用为 REST 统计数据）。
• 大多数检查清单会漏掉的约束。 禁止使用的参数值以及调用顺序要求（“先创建 X，再调用 Y”）是 Tufts 的一项定性研究（VL/HCC 2023）发现的常见疏漏，即使参数和错误已得到记录也不例外。
• 内容偏移。 参考文档页面属于查阅型内容（Diátaxis）：按产品结构组织，用于查询事实。实际操作示例符合该类型；“为何采用这种设计”的岔题或嵌入式教程则属于内容偏移——应将其标出，因为冗长文本会伪装成内容完整。

只有真正实现了各语言对等性，才计入覆盖范围：每个操作都要为每种已发布 SDK 语言提供一个代码片段，且代码片段必须实际调用 SDK，不能只是将通用 HTTP/curl 示例块按标签改成不同语言。

3. 评分并报告

提交审计报告，而不是固定清单：

• 相对于盘点结果的覆盖率百分比：已记录的操作、完整记录的参数、已记录的响应（每个操作至少包含 ≥1 个 4xx）、记录了原因和解决方法的错误代码、各语言代码片段对等性。
• 按严重性级别整理的端点发现表。
• 对澄清问题 2 所述偏移的诊断：手工维护的参考文档意味着每项发现都会反复出现；报告第一段必须说明这一点。
• 基于可核查机制进行基准比较，不要依赖声誉。按名称引用两者；评分标准文件中的报告模板说明了适用位置：
  • Stripe：参考文档由规范生成，示例中嵌入实时、个性化的测试密钥，资源 ID 带有类型前缀（如 ch_/cus_），并在工程职级评定中纳入文档质量。
  • Twilio：每个端点都有错误表，且有公开的 CI 测试代码片段仓库；每个示例在合并前都会对一个伪造 API 服务运行测试。

4. 选择修复级别

关闭差距并防止差距再次出现的三个级别。排序如下：

• 工作量：完整的生成式文档迁移 > lint 门禁 + 契约测试 > 仅 lint 门禁

• 价值：完整的生成式文档迁移 > lint 门禁 + 契约测试 > 仅 lint 门禁

• 效率：lint 门禁 + 契约测试 > 仅 lint 门禁 > 完整的生成式文档迁移

• 默认级别：lint 门禁 + 契约测试（下文阶段 2-3）。规范 linter 会在每个 PR 中以机械方式强制检查完整性；契约测试则确保规范符合实际运行的 API——没有契约测试覆盖的规范，只是格式更好的未经验证的文字。设置需要一两天，其中大部分时间用于分诊首次运行发现的问题，由一个团队负责，并能将审计从一次性工作转变为常设门禁。

• 在尚无可安全调用的测试环境时，降级为仅 lint 门禁。 工作量近乎为零——一两个小时就能在 CI 中加入 linter——但它只能验证规范是否自洽，无法验证规范是否属实。一旦有了沙盒环境，就应立即升级回去。

• 在没有可安全调用的环境时，直接移除契约测试，而非降级。 如果问题 4 的答案确认没有任何地方可以让基于属性的测试发出真实请求，那么契约测试这一档就完全不属于本次讨论的选项——这不是较慢的选项，而是根本无法执行的选项。不将它放在列表底部，是因为“我们也会加入契约测试”会在每个计划中反复出现，却悄无声息地永远无法交付。重新纳入的触发条件：有可供测试套件调用的沙盒或预发布环境。

• 升级为完整的生成式文档迁移——事实来源生成平台加上由 SDK 生成的代码片段（阶段 1+4）。这是最容易被忽视的选项：价值最高，工作量也最大（平台迁移需要数周），因此在效率比较中总是落败。不过，满足以下任一条件时，都应将它升级：参考文档由人工维护（这时漂移是结构性问题——没有任何门禁能保护不会重新生成的页面），或者文档平台或 SDK 生成变更已经列入计划，使边际成本变得很低。

• 此排序只是默认方案，并非铁律。应结合澄清问题 6 和你对团队的了解重新排序，并说明哪个答案让哪个选项发生了变化：

  • 近期有严格的截止期限时，可将仅 lint 门禁级别作为第一步。
  • 要求设置常设门禁时，可升级迁移方案；若只是一次性清理，则进一步降低其优先级。
  • 如果有内部文档平台团队，迁移几乎不费成本，胜出方案也会随之彻底改变。

各级别对应的工具选项见 references/tooling-catalog.md。

5. 执行分阶段推广

分为五个阶段，必须严格按顺序推进——每个阶段都以之前的阶段已完成为前提。绝不要向未完成阶段 1 的团队建议进入阶段 3。已达到的阶段同时作为成熟度评分。

1. 采用唯一事实来源。 参考页面根据规范生成。端点表不再手动编辑。通过标准：绝不单独于规范编辑任何参考页面。

2. 在 CI 中设置完整性门槛。 每个涉及规范的 PR 都会运行规范检查工具，要求每个操作都有描述和 operationId、记录响应（包括 4xx），并为参数和架构提供示例。起初采用警告级别。检查结果干净后，切换为警告即失败。通过标准：所选规则集下的检查错误为零，或在类似 RateMyOpenAPI 的评分中达到 ≥80/100（80 是 Zuplo 自身默认的通过门槛——它是针对单个规范的机制，也是工具默认值，并非行业平均值，因此绝不要将其说成行业平均值）。

3. 通过契约测试把控准确性。 针对架构进行基于属性的测试、检查是否符合已记录的契约，并检测破坏性变更。预计会发现问题：实践者报告称，首次对生产环境架构运行 Schemathesis，通常会发现 5-15 个问题。通过标准：对于任何生成输入导致的 500 响应、任何违反架构的响应，以及任何未通过差异检测发现的破坏性变更，CI 都会失败。

4. 实现代码片段一致性与交互性。 通过 SDK 生成器使用 x-codeSamples 提供各语言示例，或采用类似 Twilio 的 CI 测试代码片段仓库。添加预填测试凭据的试用控制台（Stripe 模式）。通过标准：每种已发布语言都为每个操作提供可运行的示例。代码片段存在后，由 samber/developer-relations-skills@docs-code-sample-standards 负责示例治理和测试——本技能的一致性门槛为该技能提供语料。

   试用功能的效果数据由供应商提供，且未能清晰区分各项因素：

   • Postman 自身的实验报告称，使用可直接运行的集合后，开发者的速度提升了 1.7x-56x。
   • Postman 关于 Moneris 客户的案例称，首次调用所需时间缩短约 10 倍，注册量增加 225%。

   两项数据都应作为标明名称的供应商案例研究引用，绝不要称为受控实验结果；并指出它们将控制台的影响与整体入门体验改善的影响混为一谈。

5. 将实践制度化。

   • 每个更改 API 的 PR 都要包含相应的规范/文档变更。
   • 将文档要求纳入 PR 审查和工程职级体系（Stripe 的做法）。
   • 每季度根据支持工单和文档搜索分析重新审核。

   升级触发条件：调查中持续出现“文档不一致”的投诉或“翻查源码”的行为，意味着需要指定专门的文档负责人并设置更严格的门槛，而不是再做一次审核。

6. 测量、设定门槛并重新审计

门槛——迭代直至全部通过：

根据第 4 步选定的整改层级，确定适用的门槛，然后迭代直至范围内的每项门槛都通过。所选层级未涵盖的阶段，其门槛不算失败——要求仅做 lint 的团队通过契约门槛，等于否定了本技能为他们规定的级别；如实的报告应写明“此层级不适用”，而不是“失败”。

• 普查覆盖率：100%——适用于所有层级。
  • 每个规范操作都出现在已发布的参考文档中。
  • 每个参数都包含类型、必填状态、描述和示例。
  • 每个响应代码都有文档说明，且每个操作至少包含一个 4xx。
  • 每个可观察到的错误代码都有原因和修复方法说明。
  • 已记录但已移除的端点数量为零。
• Lint 门槛：零错误，达到所选规则集的要求（见上文第 2 阶段的阈值）——适用于所有层级。
• 契约门槛：零违规（见上文第 3 阶段的阈值）。
  • 从默认级别起适用。
  • 仅做 lint 的级别不适用，因为该级别没有可调用环境；一旦有了可调用环境，此门槛即适用。
• 代码片段一致性：所有操作 × 已发布语言，达到 100%。
  • 仅在全面迁移到生成式文档时适用（第 4 阶段）。
  • 低于该层级时，将一致性记录为测得的百分比和一项发现，而不是未通过的门槛。

需关注的趋势，绝不作为门槛：

• 首次调用耗时（目标低于 10 分钟，这是从业者共识的上限）。自行测量整改前后的数据，不要重复使用供应商给出的倍数。
• 由参考文档内容缺失或错误导致的支持工单占比。
• 搜索文档但没有返回结果的查询。

公开数据与自行设定的数据：

• 80/100 的 lint 标准、首次运行发现的 5-15 项契约问题，以及调查和规范语料库的数据，均为公开数据（详情见 references/measured-evidence.md）。
• 100% 普查覆盖率门槛是本技能自行定义的完成标准——对于遇到一个未记录端点的集成方来说，完整性是非此即彼的。

失败模式

• 对照渲染后的页面自行审计，而不是对照规范和实际运行的接口——会完全漏掉未记录的端点，这是最严重的缺口类型。
• 将未经 lint 且未经契约测试的规范视为事实依据；普查会继承其中所有错误。
• 将“文档网站可以顺利重建”视为通过门槛——即便规范对 API 描述有误，网站仍然可以顺利重建。
• 将更换标签的 curl 计作多语言一致性。
• 只记录 2xx 路径，就称端点已覆盖。
• 用教程文字填充内容单薄的页面，而非补充事实——将象限偏移误判为完整性。
• 发布审计结果，却没有后续 CI 门槛；同样的问题下个季度还会出现。
• 在团队尚未完成前一阶段时，就建议他们进入后续阶段。
• 引用供应商的试用倍数或 OASQuali 百分比，却不标注其证据质量。

调用示例

• “根据这份 OpenAPI 规范审计我们的 API 参考文档——我觉得有一半错误代码没有记录。”
• “集成方一直在提交工单，询问文档里没有的参数。衡量一下我们的参考文档到底有多完整，并告诉我应该先修复什么。”
• “设置 CI 门槛，防止我们的 API 文档再次偏离规范——我们有可用的沙盒环境。”
• “我们在 CMS 中手动编写参考页面。它们总是过时，是这个原因吗？迁移到根据规范生成的文档需要做什么？”

参考资料

• ./references/audit-rubric.md - 按端点划分的评估标准条目，包含严重性等级、普查和报告模板，以及 Stripe/Twilio 可核查机制检查清单。
• ./references/tooling-catalog.md - 按推广阶段整理的规范检查工具、契约测试工具、代码片段一致性生成器和文档平台，并注明已知注意事项。
• ./references/measured-evidence.md - 此技能引用的每项数据，包括其来源和证据质量标签（同行评审、调查自报、供应商案例研究、从业者共识）。
• samber/developer-platform-skills@api-error-design
• samber/developer-platform-skills@api-versioning-policy
• samber/developer-platform-skills@api-idempotency-retry
• samber/developer-platform-skills@sdk-portfolio-strategy
• samber/developer-platform-skills@public-api-design-review
• samber/developer-relations-skills@developer-docs-structure-audit