SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场api-designer

api-designer

编程与开发

查看项目

更新于 10-16 02:05

技能介绍

API Designer 是一个契约优先的 API 设计技能，覆盖 REST、GraphQL 和 gRPC 三种协议。它能够生成 OpenAPI 3.1 规范、审查现有 API、分析向后兼容性，并搭建客户端代码结构。

用途

该技能用于 API 架构设计与 OpenAPI 规范相关工作，包括：从需求设计新 API、从现有代码生成规范、审计 API 设计、制定版本与弃用策略、分析规范版本间的破坏性变更，以及搭建客户端代码结构。它不适用于 MCP 服务器 API、前端 API 客户端实现、API 网关配置、运行时 API 测试或负载测试、数据库模式设计。

主要能力

技能通过模式菜单提供六种操作模式：

  • Design：从需求设计新 API，包括解析需求、资源建模、端点设计、请求/响应模式定义、认证策略推荐、错误契约定义、分页与过滤、速率限制建议，并生成完整的 OpenAPI 3.1 YAML。
  • Spec：从现有代码生成 OpenAPI 3.1 规范，扫描代码库中的路由定义、控制器、处理器和装饰器，提取端点并推断模式，最后生成规范并输出缺口报告。
  • Review：审计现有 API 设计，进行只读分析，包括解析规范、运行验证器、生成端点矩阵、检查约定、安全审计和一致性检查，并按严重程度报告发现。
  • Version：制定版本与弃用策略，分析当前状态、推荐版本策略（URL 路径、请求头或查询参数）、制定弃用计划、生成版本矩阵和迁移指南模板。
  • Compat：对比两个规范版本的向后兼容性，加载新旧规范、运行兼容性检查器、分类变更（破坏性与非破坏性）、评估影响并提供修复建议。
  • SDK：从规范搭建客户端代码结构，解析规范、按资源分组、生成客户端骨架、集成认证、处理错误并提供使用示例。注意：SDK 模式仅生成结构性脚手架，并非可发布的 SDK 包。

使用方式

技能通过命令参数或自然语言触发。支持的操作包括：design <requirements>、spec <code or path>、review <spec or path>、version <spec or path>、compat <old> <new>、sdk <spec or path>。无参数时显示模式菜单。

技能会先检测 API 协议（REST、GraphQL 或 gRPC），根据文件扩展名、关键词、URL 模式和代码模式进行判断。若信号不明确，会询问用户选择协议；若无协议上下文，默认使用 REST 并注明假设。

技能包含三个脚本：

  • scripts/api-spec-validator.py：验证 OpenAPI 3.x 的完整性和最佳实践
  • scripts/api-endpoint-matrix.py：从规范提取端点清单
  • scripts/compat-checker.py：对比两个规范的破坏性变更

脚本调用方式：

uv run python skills/api-designer/scripts/api-spec-validator.py <spec-path>
uv run python skills/api-designer/scripts/api-endpoint-matrix.py <spec-path>
uv run python skills/api-designer/scripts/compat-checker.py <old-spec> <new-spec>

所有脚本将 JSON 输出到 stdout，警告输出到 stderr。

技能还包含参考文件，按需加载：references/rest-conventions.md、references/graphql-patterns.md、references/grpc-patterns.md、references/versioning-strategies.md，以及数据文件 data/http-conventions.json 和 data/status-codes.json。

适用场景

适用于需要设计新 REST、GraphQL 或 gRPC API 的团队，需要从现有代码生成 OpenAPI 规范的场景，需要审查和审计 API 设计的场景，需要制定版本策略和弃用计划的场景，需要分析规范版本间破坏性变更的场景，以及需要搭建客户端代码结构的场景。

限制

  • 不适用于 MCP 服务器 API（应使用 mcp-creator）
  • 不适用于前端 API 客户端实现
  • 不适用于 API 网关配置
  • 不适用于运行时 API 测试或负载测试
  • 不适用于数据库模式设计（应使用 database-architect）
  • SDK 模式仅生成结构性脚手架，不声称输出可直接用于生产
  • 所有规范目标为 OpenAPI 3.1，不生成 Swagger 2.0 或 OpenAPI 3.0
  • 生成的规范必须通过 api-spec-validator.py 验证后才能呈现给用户
  • 每个端点必须至少定义一个错误响应（4xx 或 5xx）
  • 列表端点必须设计分页
  • 兼容模式中的破坏性变更必须包含修复建议
  • 进入任何模式前必须检测协议，不能无证据假设 REST
  • 协议不明确时必须询问用户，不能猜测
  • 使用规范词汇：用 "spec" 而非 "swagger"，用 "endpoint" 而非 "route"
  • 不要一次性加载所有参考文件，仅加载检测到的协议和活动模式所需的文件