SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 10-16 03:42

技能介绍

用途:在实现之前完成以消费者为中心的 API 设计,产出结构一致、文档完善的端点设计与 OpenAPI/Swagger 规范,覆盖资源建模、认证、分页、错误处理与版本化。

主要能力:分四阶段推进。阶段一发现,逐个提问资源实体、关系、所需操作、消费者类型、认证授权、限流配额、API 范式、版本策略、分页方式与既有约定,并给出 REST/GraphQL/tRPC 选择对照表;阶段二设计端点,为每个端点定义方法、路径、用途、请求头、查询参数、请求体、成功响应与错误响应,附 HTTP 方法、分页方式、状态码对照表;阶段三生成 OpenAPI 3.1.0 规范;阶段四在明确批准后保存到 docs/api/YYYY-MM-DD-<api-name>.yaml 并提交。

使用方式:按阶段执行,每阶段结束需用户确认后再继续;发现阶段一次只问一个问题。设计原则包括集合用复数名词、正确使用 HTTP 方法与状态码、统一错误格式、列表端点默认分页、支持过滤排序、PUT/DELETE 幂等。

适用场景:设计新 API、定义请求响应模式、生成 OpenAPI 规范、在 REST/GraphQL/tRPC 之间选型、建立 API 约定。

限制:不跳过发现阶段,不在未定义错误响应时设计端点,列表端点必须分页,命名需一致,未获用户批准不得生成规范,无明确理由不得混用 API 范式。完成后需校验端点模式、错误格式、认证、分页与 YAML 有效性。具体安装命令与价格暂未提供。