SuperAPI AI 工具集

reviewing-api-spec

编程与开发

查看项目

更新于 10-16 05:01

技能介绍

用途:这是“编写/评审 api-spec”配对中的评审一半。当拿到一份已完成的 api-spec 文档(操作、请求/响应 schema、认证、错误模型、分页/限流、版本化、示例)时,判断客户端工程师能否仅凭该文档正确调用每个操作、服务端工程师能否据此实现,且对形状、错误、认证无歧义。适用于集成或实现前的验收决策、对修订后文档的复审,以及对变更请求的增量评审。

主要能力:按固定的 11 项契约完整性清单逐条判定通过或缺口,覆盖风格/基址/版本化、操作清单与追溯、双向类型化、认证与逐操作授权、完整错误模型、共享类型复用、分页过滤排序与限流、示例一致性、命名与版本一致性、真实性与一致性,以及(仅增量时)变更范围、分类、波及与版本化。输出一行机器可解析的判定:VERDICT: approve 或 VERDICT: revise,随后列出可执行发现(失败条件、位置、修复方式)。

使用方式:先通读整份契约,识别 API 风格(REST/GraphQL/gRPC,可能混合),再逐条判定;判定只依据真实且具名的缺陷,不因风格偏好或字数制造缺口。评审者只判定、不编写或改写契约,由生产者修订。

限制:不适用于编写或修复 api-spec、评审数据模型或功能规格、评审面向消费者的 api-reference、评审实现代码、评审通用设计文档,或检查模板/章节一致性。风格无关:不得因 GraphQL/gRPC 契约缺少 HTTP 状态码或 OpenAPI 而要求修订。无 capability_record 时能力边界项记为 n/a;绿地首版无变更请求时增量条件为 n/a。具体命令、安装方式与收费信息暂未提供。