用途:在需要设计 REST 或 GraphQL API、编写 OpenAPI 规范或规划 API 架构时使用,覆盖资源建模、版本策略、分页、错误处理与契约验证。
主要能力:按“分析领域—建模资源—设计端点—编写契约—Mock 验证—规划演进”的工作流推进;产出资源模型与关系、端点 URI 与 HTTP 方法、OpenAPI 3.1 规范、认证授权流程、错误响应目录、分页与过滤模式、版本与弃用策略。约束要求遵循 REST 原则、统一命名、为集合端点实现分页、记录认证授权、提供请求响应示例;禁止在 URI 中使用动词、返回不一致结构、忽略状态码语义、无版本策略、无迁移路径的破坏性变更、省略限流考虑。
使用方式:编写 OpenAPI 3.1 规范后运行 npx @redocly/cli lint openapi.yaml 校验,再用 npx @stoplight/prism-cli mock openapi.yaml 启动 Mock 服务器验证契约。错误响应采用 RFC 7807 Problem Details,Content-Type 为 application/problem+json,type 为稳定文档化 URI,detail 需可读可操作,可用 errors[] 扩展字段级校验失败。
适用场景:API 架构设计、契约先行开发、接口评审与文档生成、SDK 生成前的规范准备。
限制:资料未提供具体收费、价格、平台支持范围与效果数据;GraphQL 相关细节仅提及为专长方向,未展开具体规范或工具链。