SuperAPI AI 工具集

api-design

编程与开发

查看项目

更新于 11-17 18:41

技能介绍

用途

该技能面向 API 的完整设计与交付流程,覆盖从接口契约与 schema 设计,到 mock 服务与开发者文档,再到契约测试与集成测试的几个阶段。适用于需要创建 OpenAPI schema、REST、GraphQL 或 gRPC 接口,或为其编写文档与契约测试的场景。

主要能力

阶段一:API 契约与 schema 设计

定义 OpenAPI 3.1 / GraphQL schema,包含描述性的 summary、输入参数、响应 schema 与错误结构。执行 API 设计规范:可预测的 URI 命名(如 /v1/resources/{id})、正确的 HTTP 状态码(200、201、204、400、401、403、404、409、422、500)以及一致的 JSON schema。

阶段二:Mock 与开发者文档

生成动态 mock 数据生成器(Prism、MSW、GraphQL Mocking)。产出包含 cURL、JavaScript/TypeScript、Python、Go 代码片段的完整交互式文档。

阶段三:契约与集成测试

编写自动化契约测试(Pact、Newman、Jest),确保后端响应符合 OpenAPI 规范。校验分页(cursor / limit)、过滤与限流响应头的实现。

验证与质量清单

  • schema 通过 OpenAPI 3.1 linter 且零错误。
  • 所有错误响应遵循标准 schema(RFC 7807 Problem Details)。
  • 针对语义化版本策略检查破坏性变更。

使用方式与约束

在 REST API 中,不得对错误响应返回 HTTP 200 OK 并在响应体中嵌入 { error: true };不得在 API 错误响应体中泄露内部堆栈跟踪或数据库列名。任务需要时可加载参考文件 references/openapi-spec.md。

适用场景与限制

适合进行 REST、GraphQL、gRPC 接口的契约设计、文档生成与契约测试。具体支持的平台、安装方式、收费情况与效果数据暂未提供。