SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场api-reference-quality

api-reference-quality

测试与质量

查看项目

更新于 10-16 11:56

技能介绍

用途

api-reference-quality 是一个 API 参考文档审计技能。它帮助判断已发布的 API 参考文档是否完整记录了 API 的完整契约表面，使集成方无需猜测、阅读源代码或提交工单。其核心框架为：参考文档是 API 契约的投影；如果手工编写，就会成为仅靠人力同步的第二副本。因此，审计发现的每一项问题要么是完整性缺口，要么是漂移机制，而漂移的修复方式始终是结构性的。

该技能期望发现问题是行业常态而非例外。它引用的证据包括：OASQuali（ICWE 2026，2,529 份公开 OpenAPI 规格）测得平均文档质量为 67.11%，其中 86.95% 的规格缺少参数示例；Postman 2024 年 API 状态调查（5,600+ 受访者）发现 39% 的人将文档不一致视为最大障碍，44% 的人会翻查源代码来理解 API。

主要能力

  1. 表面清点：以规格为清点来源，枚举每个操作、参数、响应码和声明的错误；无规格时从路由定义、网关配置或 SDK 方法列表枚举，并将“无规格”记录为首个阻塞性发现。双向比对规格与已发布文档，识别“已记录但已移除”与“存活但未记录”的端点。

  2. 逐端点审计：按评分表对每个操作评分，记录严重级别（阻塞 / 主要 / 次要）。每个操作需要：描述、每个参数的类型/必填性/约束/示例、每个响应码（至少一个 4xx）、每个错误码及其原因与修复方式、请求与响应示例、按语言的代码片段、版本声明、幂等安全性说明。

  3. 三项常被跳过的检查：错误表面（每个错误码需记录原因与修复方式）、易被遗漏的约束（不允许的参数值与调用顺序要求）、象限漂移（参考页应为查询型，嵌入教程或设计原理阐述属于内容漂移）。

  4. 评分与报告：给出清点覆盖率百分比、带严重级别的逐端点发现表、漂移诊断结论，以及与 Stripe、Twilio 可核查机制的对标比较。

  5. 修复层级选择与分阶段推进：提供三个修复层级（全量生成式文档迁移 > lint 门禁 + 契约测试 > 仅 lint 门禁），默认档位为 lint 门禁 + 契约测试。分五阶段推进：采用唯一事实来源、在 CI 中门禁完整性、用契约测试门禁准确性、实现代码片段对等与交互性、制度化。

  6. 度量、设卡与重新审计：设定清点覆盖、lint 门禁、契约门禁、代码片段对等四类门禁，按所选层级确定范围内的门禁并迭代至全部通过；同时跟踪但不设卡的指标包括首次调用耗时、因参考内容缺失或错误导致的工单占比、无结果的文档搜索查询。

使用方式

该技能先进行澄清性提问，再开始审计。提问包括：是否存在机器可读规格（OpenAPI、AsyncAPI、GraphQL SDL）？已发布文档是由规格渲染还是手工维护？为哪些语言提供 SDK 或代码片段，片段如何产生？当前哪些 CI 门禁涉及规格或文档？谁阅读参考文档（第三方集成方、一方开发者、编码智能体）？修复上限（何时文档必须可信、是一次性清理还是长期门禁、可投入多少精力）？

随后按六个步骤执行：步骤 1 清点表面；步骤 2 逐端点审计；步骤 3 评分与报告；步骤 4 选择修复层级；步骤 5 执行分阶段推进；步骤 6 度量、设卡与重新审计。每个步骤都有对应章节。工具选项位于 references/tooling-catalog.md。

适用场景

适用于以下情形：对照 OpenAPI 规格审计 API 参考文档；集成方持续就文档缺失的参数提交工单；需要建立 CI 门禁防止文档再次与规格漂移（需要可安全调用的环境）；评估从手工维护参考页迁移到规格生成文档的成本。技能给出了调用示例，如“审计我们的 API 参考文档是否与这份 OpenAPI 规格一致——我觉得有一半错误码没有记录”“设置 CI 门禁，让 API 文档不再与规格漂移——我们有可用的沙箱环境”等。

限制

  • 本技能聚焦人类读者；编码智能体读者的规格标注问题（operationId、枚举封闭、描述拆分）应转向 samber/developer-relations-skills@coding-agent-docs-optimization，本技能不重复其规则。
  • 代码片段治理与测试在片段存在后由 samber/developer-relations-skills@docs-code-sample-standards 负责。
  • 部分修复层级有前提条件：契约测试层级在没有可安全调用的测试环境时被直接删除而非降级；仅 lint 门禁层级只验证规格自洽，不验证其真实性。
  • 技能中引用的厂商数据（如 Postman 实验称开发者在有可运行集合时快 1.7x–56x，Moneris 客户案例称首次调用时间约快 10x 且注册量增加 225%）为厂商自述，未被清晰隔离，只能作为命名厂商案例引用，不能作为对照结果；80/100 的 lint 通过线是 Zuplo 自身默认值，不是行业平均值。
  • 技能的 100% 清点覆盖门禁是该技能自身对完成的定义，并非已发布标准。

其他说明

技能列出多个失败模式，例如：对照渲染页面自身而非规格与线上表面进行审计；将未经 lint、未经契约测试的规格视为事实真相；把“文档站点重建通过”当作门禁；只记录 2xx 路径就称端点已覆盖；用教程文字填充单薄页面；发布审计但不设 CI 门禁，导致下季度同样问题重现；向缺少前置阶段的团队推荐后续阶段；引用厂商试运行倍数或 OASQuali 百分比而不标注证据质量。官方文档中未提供具体安装命令与价格信息。