用途:在设计与规划 REST 或 GraphQL API 时使用,覆盖资源建模、版本策略、分页过滤、错误响应标准化、认证流程规划与 API 契约文档化。
主要能力:按“分析领域→建模资源→设计端点→编写契约→规划演进”的工作流推进;产出资源模型与关系、端点规范(URI 与 HTTP 方法)、OpenAPI 3.1 规范(YAML 或 JSON)、认证与授权流程、错误响应目录、分页与过滤模式、版本化与弃用策略。可按需加载参考文档:REST 模式、版本化、分页、错误处理、OpenAPI。
必须遵循:符合 REST 原则与正确 HTTP 方法;命名一致(snake_case 或 camelCase);提供完整 OpenAPI 3.1 规范;错误响应含可操作信息;集合端点实现分页;版本化并明确弃用策略;记录认证与授权;提供请求/响应示例。
禁止事项:资源 URI 中使用动词;返回结构不一致;省略错误码文档;忽略 HTTP 状态码语义;无版本策略;暴露实现细节;无迁移路径的破坏性变更;忽略限流考虑。
知识范围:REST 架构、OpenAPI 3.1、GraphQL、HTTP 语义、JSON:API、HATEOAS、OAuth 2.0、JWT、RFC 7807、版本化模式、分页策略、限流、Webhook 设计、SDK 生成。
限制:资料未提供具体安装命令、收费与价格、支持平台及实际效果数据;具体用法需结合所在工具环境,参考文件路径以资料为准。