mcpField
A
api-designer

api-designer

github.com/wyattowalsh开发549 次安装9 周前更新
代码仓库

关于 api-designer

api-designer 是面向 API 开发者的契约优先设计技能，支持 REST、GraphQL 和 gRPC。它可生成 OpenAPI 3.1 规范、审查设计、分析兼容性并搭建客户端代码结构。

主要功能

  1. 01设计 REST、GraphQL 和 gRPC API
  2. 02生成 OpenAPI 3.1 规范
  3. 03审查 API 设计与安全性
  4. 04分析版本间兼容性
  5. 05搭建客户端代码结构

适用场景

  1. 01根据需求设计新 API
  2. 02从现有代码生成 API 规范
  3. 03评估变更是否破坏兼容性
  4. 04规划 API 版本与弃用

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/wyattowalsh/agents --skill api-designer

安装后在 Claude Code 中输入/api-designer确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

data/
http-conventions.json
status-codes.json
evals/
api-design.json
compat-mode.json
evals.json
explicit-invocation.json
implicit-trigger.json
negative-control.json
references/
graphql-patterns.md
grpc-patterns.md
rest-conventions.md
versioning-strategies.md
scripts/
api-endpoint-matrix.py
api-spec-validator.py
check.py
compat-checker.py
scripts/asset_toolkit/
__init__.py
_shared.py
common.py
package.py
validate_evals.py
validate_hooks.py
validate_skill.py
templates/
dashboard.html

详细介绍

API Designer

跨 REST、GraphQL 和 gRPC 进行契约优先的 API 设计。生成 OpenAPI 3.1 规范，审查现有 API，分析向后兼容性，并搭建客户端代码框架。

规范术语

术语定义
spec描述 API 接口面的 OpenAPI 3.1 文档（YAML 或 JSON）
endpointREST API 中的路径 + 方法组合；GraphQL 中的查询/变更；gRPC 中的 RPC
breaking change任何会导致现有客户端在不修改代码的情况下无法运行的变更
non-breaking change向后兼容的变更（新增字段、新端点、可选参数）
resource通过 API 暴露的领域实体（REST 中基于名词的 URL 路径段）
contractAPI 生产者与消费者之间由 spec 定义的正式约定
protocolAPI 范式：REST、GraphQL 或 gRPC
surfaceAPI 暴露的全部端点、类型和操作
versioning strategy传达 breaking change 的方式：URL 路径、标头或查询参数

分派

$ARGUMENTS操作
design <requirements>根据需求设计新 API
spec <code or path>根据现有代码生成 OpenAPI 3.1 spec
review <spec or path>审查现有 API 设计
version <spec or path>制定版本管理和弃用策略
compat <old> <new>分析向后兼容性差异
sdk <spec or path>搭建客户端代码结构
关于 API 设计的自然语言描述根据意图自动检测模式
空显示含示例的模式菜单
模式菜单（参数为空时）
#模式示例
1设计design "User management API with RBAC"
2Specspec src/routes/
3审查review openapi.yaml
4版本管理version openapi.yaml
5兼容性compat v1.yaml v2.yaml
6SDKsdk openapi.yaml

选择一个编号，或描述你的需求。

协议检测

进入任何模式之前，先根据输入检测 API 协议。分类结果决定适用的约定和模式。

检测信号：

信号RESTGraphQLgRPC
文件扩展名.yaml、.json（OpenAPI）.graphql、.gql.proto
关键词endpoint、resource、CRUD、pathquery、mutation、subscription、resolverservice、rpc、message、protobuf
URL 模式/api/v1/resources/graphqlgRPC 服务名称
代码模式Express/FastAPI 路由、控制器Schema 定义、解析器Proto 服务定义

路由规则：

  • 信号明确指向一种协议：按该协议的约定继续
  • 信号混杂或存在歧义：询问用户 —“使用哪种协议？[REST / GraphQL / gRPC]”
  • 没有协议上下文（仅有需求）：默认使用 REST，并说明这一假设

根据检测到的协议，加载 references/rest-conventions.md、references/graphql-patterns.md 或 references/grpc-patterns.md。

模式 A：设计

根据需求设计新 API。读取 references/rest-conventions.md（或特定协议的参考文档）。

设计步骤
  1. 解析需求 — 提取资源、关系、操作、身份验证需求和约束
  2. 资源建模 — 定义资源及其属性、关系和基数
  3. 端点设计 — 按照协议惯例，将 CRUD 和自定义操作映射到端点
  4. 请求/响应架构 — 定义负载及其类型、验证规则和示例
  5. 身份验证策略 — 根据使用场景推荐身份验证方式（API 密钥、OAuth2、JWT）
  6. 错误约定 — 定义错误响应格式，包括代码、消息和详细信息对象
  7. 分页与筛选 — 应用游标或偏移量分页，采用筛选查询模式
  8. 速率限制 — 根据端点敏感度和预期负载推荐限制
  9. 生成规范 — 输出完整的 OpenAPI 3.1 YAML
  10. 验证 — 对生成的规范运行 scripts/api-spec-validator.py

模式 B：规范

从现有代码生成 OpenAPI 3.1。

规范步骤
  1. 扫描代码库 — 读取路由定义、控制器、处理程序和装饰器
  2. 提取端点 — 将代码映射为路径、方法、参数和响应类型
  3. 推断架构 — 根据类型注解或运行时类型构建请求/响应架构
  4. 生成规范 — 输出包含所有已发现端点的 OpenAPI 3.1 YAML
  5. 验证 — 运行 scripts/api-spec-validator.py
  6. 差距报告 — 列出缺少描述、示例或错误响应的端点

模式 C：审查

审计现有 API 设计。仅进行只读分析。

审查步骤
  1. 解析规范 — 加载并验证 OpenAPI 文档
  2. 运行验证器 — 使用 scripts/api-spec-validator.py 检查结构问题
  3. 运行端点矩阵 — 使用 scripts/api-endpoint-matrix.py 查看 API 接口概览
  4. 检查惯例 — 根据 references/rest-conventions.md 验证命名、HTTP 方法用法和状态码
  5. 安全审计 — 检查身份验证覆盖范围、HTTPS 强制执行情况和敏感数据泄露情况
  6. 一致性检查 — 验证命名模式、响应封装一致性和错误格式统一性
  7. 报告 — 按严重程度（严重、警告、信息）呈现发现的问题，并提供具体的修复建议

模式 D：版本

版本管理和弃用策略。

版本步骤
  1. 分析当前状态 — 解析规范并识别版本标记
  2. 推荐策略 — 比较 URL 路径、标头和查询参数版本管理方式（加载 references/versioning-strategies.md）
  3. 弃用计划 — 为已弃用端点制定时间表、Sunset 标头和迁移指南
  4. 版本矩阵 — 用表格展示各版本中包含的端点
  5. 迁移指南模板 — 提供供使用方迁移文档使用的框架

模式 E：兼容性

比较两个规范版本之间的向后兼容性差异。

兼容性步骤
  1. 加载两个规范 — 解析旧版和新版 OpenAPI 文档
  2. 运行兼容性检查器 — scripts/compat-checker.py <old> <new>
  3. 变更分类 — 按变更类型和位置区分破坏性与非破坏性变更
  4. 影响评估 — 确定受影响的使用方并估算迁移工作量
  5. 补救方案 — 针对每项破坏性变更，提出向后兼容的替代方案

模式 F：SDK

根据规范搭建客户端代码结构。不是可发布的 SDK 包，而是结构框架。

SDK 步骤
  1. 解析规范 — 提取端点、架构和身份验证要求
  2. 按资源分组 — 将端点整理到逻辑清晰的客户端模块中
  3. 生成客户端框架 — 生成带类型化参数和返回类型的方法存根
  4. 身份验证集成 — 在客户端构造函数中接入身份验证机制
  5. 错误处理 — 将 API 错误代码映射为客户端异常
  6. 用法示例 — 为每种资源提供一个示例，展示常见操作

脚本

脚本用途运行时机
scripts/api-spec-validator.py验证 OpenAPI 3.x 的完整性和最佳实践设计、规范、评审
scripts/api-endpoint-matrix.py从规范中提取端点清单评审、版本、SDK
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.mdREST 最佳实践、HTTP 方法、状态码、命名、分页、速率限制设计、规范、评审（REST）
references/graphql-patterns.mdGraphQL 模式设计、查询模式、错误处理、订阅设计、规范、评审（GraphQL）
references/grpc-patterns.mdgRPC 服务模式、proto 设计、流式传输、错误码设计、规范、评审（gRPC）
references/versioning-strategies.mdURL、标头与查询参数版本控制、弃用、向后兼容性检查清单版本、兼容性
data/http-conventions.jsonHTTP 方法语义参考数据脚本
data/status-codes.jsonHTTP 状态码指南参考数据脚本

不要一次性加载所有参考资料。仅加载检测到的协议和当前模式所需的内容。

重要规则

  1. 进入任何模式前，始终先检测协议——没有依据时，绝不假定是 REST
  2. 如果协议不明确，请询问用户——不要猜测
  3. 生成的规范在呈现给用户前必须通过 api-spec-validator.py 验证
  4. 每个端点都必须至少定义一个错误响应（4xx 或 5xx）
  5. 为返回集合的列表端点设计 API 时，绝不省略分页
  6. 兼容性模式中的破坏性变更必须包含修复建议
  7. SDK 模式仅生成结构框架——绝不声称输出可用于生产环境
  8. 始终一致地使用规范术语——使用“规范”，而非“swagger”；使用“端点”，而非“路由”
  9. 所有规范均以 OpenAPI 3.1 为目标——不要生成 Swagger 2.0 或 OpenAPI 3.0
  10. 不适用于 MCP 服务（请使用 mcp-creator）或前端 API 客户端代码

范围边界

适用于：

  • 根据需求设计新的 REST、GraphQL 或 gRPC API
  • 根据现有代码生成 OpenAPI 规范
  • 评审和审计 API 设计
  • 版本控制策略和弃用规划
  • 分析规范版本之间的破坏性变更
  • 搭建客户端代码结构

不适用于：

  • MCP 服务 API（请使用 /mcp-creator）
  • 前端 API 客户端实现
  • API 网关配置
  • 运行时 API 测试或负载测试
  • 数据库模式设计（请使用 /database-architect）

评论

支持 Markdown