SuperAPI AI 工具集

reviewing-api-reference

编程与开发

查看项目

更新于 10-16 05:01

技能介绍

用途:这是 API 参考文档“编写/评审”配对中的评审一半。当一份已完成(或修订后)的、面向集成开发者的已发布 API 参考需要发布前的通过/修订决定时启用;也用于对修订稿复审,或对上游契约变更后的增量修订做 delta 范围评审。它只判断,不撰写、修复或重写文档。

主要能力:按固定的 11 项可用性 + 契约一致性检查表逐条判定通过或缺口,包括:首次调用可达(getting-started 与认证能端到端跑通,含 401/403 失败案例);每个操作都有文档(含契约声明的事件/webhook,含用途、类型化参数、请求与响应示例、错误响应);错误为一等公民(统一错误体、机器可读 code、状态码表、按端点错误行);速率限制(429、Retry-After、RateLimit-* 头、退避与抖动、幂等键);与交付的 api-spec 一致(无漂移、无捏造,最关键维度);示例可运行;版本与弃用说明;共享对象只定义一次;内容有据、缺口显式标注;分页/列表约定按比例;修订时 delta 重新同步。

使用方式:先通读整份参考并加载上游 api-spec 作为覆盖清单与一致性依据;逐条判定;输出单行 VERDICT: approve 或 VERDICT: revise,随后列出可执行发现(失败条件、精确位置、修复方式)。若未提供 api-spec,须在发现中明确声明该假设,一致性维度只能按文档内部自洽判断。

适用场景:面向集成开发者的已发布 API 参考的验收门;独立评审者复核作者产出;修订稿复审;契约变更后的增量评审。

限制:不适用于撰写或修复参考(用 api-reference-authoring)、评审终端用户产品指南、评审开发者采用/集成指南、评审工程 api-spec 本身、检查模板/章节合规、或评测线上 API 实现。不得为凑数或示好而误判;比例化裁剪不算缺口;渲染文档站功能(搜索、交互式 try-it、无障碍/国际化)不在范围内。具体命令与代码示例资料未提供。