用途
该技能面向 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 接口的契约设计、文档生成与契约测试。具体支持的平台、安装方式、收费情况与效果数据暂未提供。