用途
API Designer 是一个用于设计 REST 或 GraphQL API 的技能，也可用于创建 OpenAPI 规范或规划 API 架构。其定位是资深 API 架构师，拥有 10 年以上创建直观、可扩展 API 架构的经验，专长包括 REST 设计模式、OpenAPI 3.1 规范、GraphQL schema，以及构建兼顾性能、安全与可维护性的 API。
主要能力
该技能覆盖以下设计任务：
- 设计新的 REST 或 GraphQL API
- 创建 OpenAPI 3.1 规范
- 资源与关系建模
- 实施 API 版本化策略
- 设计分页与过滤
- 标准化错误响应
- 规划认证流程
- 编写 API 契约文档
使用方式
该技能定义了核心工作流：
- 分析领域——理解业务需求、数据模型、客户端需求
- 建模资源——识别资源、关系、操作
- 设计端点——定义 URI 模式、HTTP 方法、请求/响应 schema
- 编写契约——创建带完整文档的 OpenAPI 3.1 规范
- 规划演进——设计版本化、弃用、向后兼容
技能还提供按上下文加载的参考指南，包括：REST 模式（资源设计、HTTP 方法、HATEOAS）、版本化（API 版本、弃用、破坏性变更）、分页（游标、偏移、键集分页）、错误处理（错误响应、RFC 7807、状态码）、OpenAPI（OpenAPI 3.1、文档、代码生成）。
设计约束
必须遵循：遵循 REST 原则（面向资源、正确的 HTTP 方法）；使用一致的命名约定（snake_case 或 camelCase）；包含完整的 OpenAPI 3.1 规范；设计带有可操作消息的正确错误响应；为集合端点实现分页；为 API 版本化并制定清晰的弃用策略；记录认证与授权；提供请求/响应示例。
必须避免：在资源 URI 中使用动词（应使用 /users/{id}，而非 /getUser/{id}）；返回不一致的响应结构；跳过错误码文档；忽略 HTTP 状态码语义；在没有版本化策略的情况下设计 API；在 API 中暴露实现细节；在没有迁移路径的情况下创建破坏性变更；忽略速率限制方面的考虑。
输出模板
设计 API 时，该技能提供以下输出内容：资源模型与关系；带 URI 和方法的端点规范；OpenAPI 3.1 规范（YAML 或 JSON）；认证与授权流程；错误响应目录；分页与过滤模式；版本化与弃用策略。
适用场景
适用于需要系统化设计 API 契约、规范与演进策略的开发者与架构团队，尤其是需要产出 OpenAPI 3.1 文档、统一错误与分页模式、规划版本化与弃用的项目。
限制
资料未提供该技能的具体安装命令、运行环境要求、收费方式、价格、平台支持范围或实际效果验证信息，这些内容暂未提供。