api-designer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

API Designer

API设计器

Contract-first API design across REST, GraphQL, and gRPC. Produces OpenAPI 3.1 specs, reviews existing APIs, analyzes backward compatibility, and scaffolds client code.

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

Canonical Vocabulary

标准术语

Term	Definition
spec	An OpenAPI 3.1 document (YAML or JSON) describing an API's surface
endpoint	A path + method combination in a REST API; a query/mutation in GraphQL; an RPC in gRPC
breaking change	Any modification that causes existing clients to fail without code changes
non-breaking change	A backward-compatible modification (additive fields, new endpoints, optional params)
resource	A domain entity exposed through the API (noun-based URL segment in REST)
contract	The formal agreement between API producer and consumer defined by the spec
protocol	The API paradigm: REST, GraphQL, or gRPC
surface	The complete set of endpoints, types, and operations an API exposes
versioning strategy	How breaking changes are communicated: URL path, header, or query parameter

术语	定义
spec	描述API对外暴露内容的OpenAPI 3.1文档（YAML或JSON格式）
endpoint	REST API中的路径+方法组合；GraphQL中的查询/变更；gRPC中的RPC
breaking change	任何导致现有客户端无需修改代码即可失效的修改
non-breaking change	向后兼容的修改（新增字段、新端点、可选参数）
resource	通过API暴露的领域实体（REST中基于名词的URL段）
contract	由规范定义的API生产者与消费者之间的正式约定
protocol	API范式：REST、GraphQL或gRPC
surface	API对外暴露的所有端点、类型和操作的集合
versioning strategy	传递破坏性变更的方式：URL路径、请求头或查询参数

Dispatch

命令调度

$ARGUMENTS	Action
`design <requirements>`	Design a new API from requirements
`spec <code or path>`	Generate OpenAPI 3.1 spec from existing code
`review <spec or path>`	Audit an existing API design
`version <spec or path>`	Versioning and deprecation strategy
`compat <old> <new>`	Backward compatibility diff analysis
`sdk <spec or path>`	Scaffold client code structure
Natural language about API design	Auto-detect mode from intent
Empty	Show mode menu with examples

参数	操作
`design <requirements>`	根据需求设计新API
`spec <code or path>`	从现有代码生成OpenAPI 3.1规范
`review <spec or path>`	审计现有API设计
`version <spec or path>`	制定版本管理与弃用策略
`compat <old> <new>`	向后兼容性差异分析
`sdk <spec or path>`	搭建客户端代码结构
关于API设计的自然语言描述	根据意图自动检测模式
空参数	显示带示例的模式菜单

Mode Menu (empty args)

模式菜单（空参数）


design "User management API with RBAC"
spec src/routes/
review openapi.yaml
version openapi.yaml
compat v1.yaml v2.yaml
sdk openapi.yaml

#	Mode	Example
1	Design	`design "User management API with RBAC"`
2	Spec	`spec src/routes/`
3	Review	`review openapi.yaml`
4	Version	`version openapi.yaml`
5	Compat	`compat v1.yaml v2.yaml`
6	SDK	`sdk openapi.yaml`

Pick a number or describe what you need.


design "User management API with RBAC"
spec src/routes/
review openapi.yaml
version openapi.yaml
compat v1.yaml v2.yaml
sdk openapi.yaml

序号	模式	示例
1	设计	`design "User management API with RBAC"`
2	规范生成	`spec src/routes/`
3	评审	`review openapi.yaml`
4	版本管理	`version openapi.yaml`
5	兼容性分析	`compat v1.yaml v2.yaml`
6	SDK搭建	`sdk openapi.yaml`

选择序号或描述你的需求。

Protocol Detection

协议检测

Detect the API protocol from input before entering any mode. Classification determines which conventions and patterns apply.

Detection signals:

Signal	REST	GraphQL	gRPC
File extension	`.yaml` , `.json` (OpenAPI)	`.graphql` , `.gql`	`.proto`
Keywords	endpoint, resource, CRUD, path	query, mutation, subscription, resolver	service, rpc, message, protobuf
URL patterns	`/api/v1/resources`	`/graphql`	gRPC service names
Code patterns	Express/FastAPI routes, controllers	Schema definitions, resolvers	Proto service definitions

Routing:

Clear signal for one protocol: proceed with that protocol's conventions
Mixed signals or ambiguous: ask user — "Which protocol? [REST / GraphQL / gRPC]"
No protocol context (pure requirements): default to REST, note assumption

Load

references/rest-conventions.md

references/graphql-patterns.md

, or

references/grpc-patterns.md

based on detected protocol.

进入任何模式前先从输入中检测API协议。分类结果将决定适用的约定与模式。

检测信号：

信号	REST	GraphQL	gRPC
文件扩展名	`.yaml` , `.json` (OpenAPI)	`.graphql` , `.gql`	`.proto`
关键词	endpoint、resource、CRUD、path	query、mutation、subscription、resolver	service、rpc、message、protobuf
URL模式	`/api/v1/resources`	`/graphql`	gRPC服务名称
代码模式	Express/FastAPI路由、控制器	Schema定义、解析器	Proto服务定义

路由规则：

明确指向某一协议的信号：遵循该协议的约定继续执行
混合信号或模糊不清：询问用户 — "请选择协议？[REST / GraphQL / gRPC]"
无协议上下文（纯需求）：默认使用REST，并注明该假设

根据检测到的协议加载

references/rest-conventions.md

、

references/graphql-patterns.md

或

references/grpc-patterns.md

。

Mode A: Design

模式A：设计

New API from requirements. Read

references/rest-conventions.md

(or protocol-specific reference).

根据需求设计新API。读取

references/rest-conventions.md

（或对应协议的参考文档）。

Design Steps

设计步骤

Parse requirements — Extract resources, relationships, operations, auth needs, constraints
Resource modeling — Define resources with attributes, relationships, cardinality
Endpoint design — Map CRUD + custom operations to endpoints following protocol conventions
Request/response schemas — Define payloads with types, validation rules, examples
Auth strategy — Recommend auth approach (API key, OAuth2, JWT) based on use case
Error contract — Define error response format with codes, messages, detail objects
Pagination & filtering — Apply cursor or offset pagination, filter query patterns
Rate limiting — Recommend limits based on endpoint sensitivity and expected load
Generate spec — Output complete OpenAPI 3.1 YAML
Validate — Run
```
scripts/api-spec-validator.py
```
on generated spec

解析需求 — 提取资源、关系、操作、认证需求、约束条件
资源建模 — 定义包含属性、关系、基数的资源
端点设计 — 遵循协议约定将CRUD+自定义操作映射到端点
请求/响应 schema — 定义包含类型、验证规则、示例的负载
认证策略 — 根据使用场景推荐认证方式（API密钥、OAuth2、JWT）
错误契约 — 定义包含错误码、消息、详情对象的错误响应格式
分页与过滤 — 应用游标或偏移分页、过滤查询模式
限流策略 — 根据端点敏感度和预期负载推荐限流规则
生成规范 — 输出完整的OpenAPI 3.1 YAML文档
验证 — 对生成的规范运行
```
scripts/api-spec-validator.py
```

Mode B: Spec

模式B：规范生成

Generate OpenAPI 3.1 from existing code.

从现有代码生成OpenAPI 3.1规范。

Spec Steps

规范生成步骤

Scan codebase — Read route definitions, controllers, handlers, decorators
Extract endpoints — Map code to path + method + parameters + response types
Infer schemas — Build request/response schemas from type annotations or runtime types
Generate spec — Output OpenAPI 3.1 YAML with all discovered endpoints
Validate — Run
```
scripts/api-spec-validator.py
```
Gap report — List endpoints missing descriptions, examples, or error responses

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

Mode C: Review

模式C：评审

Audit existing API design. Read-only analysis.

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

Review Steps

评审步骤

Parse spec — Load and validate the OpenAPI document
Run validator —
```
scripts/api-spec-validator.py
```
for structural issues
Run endpoint matrix —
```
scripts/api-endpoint-matrix.py
```
for surface overview
Convention check — Verify naming, HTTP method usage, status codes against
```
references/rest-conventions.md
```
Security audit — Check auth coverage, HTTPS enforcement, sensitive data exposure
Consistency check — Verify naming patterns, response envelope consistency, error format uniformity
Report — Present findings by severity (critical, warning, info) with specific fix recommendations

解析规范 — 加载并验证OpenAPI文档
运行验证器 — 使用
```
scripts/api-spec-validator.py
```
检查结构问题
运行端点矩阵 — 使用
```
scripts/api-endpoint-matrix.py
```
获取API对外暴露内容概览
约定检查 — 根据
```
references/rest-conventions.md
```
验证命名、HTTP方法使用、状态码
安全审计 — 检查认证覆盖范围、HTTPS强制要求、敏感数据暴露情况
一致性检查 — 验证命名模式、响应信封一致性、错误格式统一性
报告 — 按严重程度（严重、警告、信息）呈现发现的问题，并提供具体修复建议

Mode D: Version

模式D：版本管理

Versioning and deprecation strategy.

制定版本管理与弃用策略。

Version Steps

版本管理步骤

Analyze current state — Parse spec, identify version indicators
Recommend strategy — Compare URL path vs header vs query param versioning (load
```
references/versioning-strategies.md
```
)
Deprecation plan — Timeline, sunset headers, migration guides for deprecated endpoints
Version matrix — Table showing which endpoints exist in which versions
Migration guide template — Skeleton for consumer migration documentation

分析当前状态 — 解析规范，识别版本标识
推荐策略 — 对比URL路径、请求头、查询参数三种版本管理方式（加载
```
references/versioning-strategies.md
```
）
弃用计划 — 弃用时间线、日落请求头、弃用端点迁移指南
版本矩阵 — 展示各版本包含的端点的表格
迁移指南模板 — 消费者迁移文档框架

Mode E: Compat

模式E：兼容性分析

Backward compatibility diff between two spec versions.

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

Compat Steps

兼容性分析步骤

Load both specs — Parse old and new OpenAPI documents
Run compat checker —
```
scripts/compat-checker.py <old> <new>
```
Classify changes — Breaking vs non-breaking with change type and location
Impact assessment — Which consumers are affected, estimated migration effort
Remediation — For each breaking change, suggest backward-compatible alternatives

加载两个规范 — 解析旧版与新版OpenAPI文档
运行兼容性检查器 — 执行
```
scripts/compat-checker.py <old> <new>
```
分类变更 — 区分破坏性与非破坏性变更，并标注变更类型与位置
影响评估 — 哪些消费者会受影响，预估迁移工作量
修复建议 — 针对每个破坏性变更，提供向后兼容的替代方案

Mode F: SDK

模式F：SDK搭建

Scaffold client code structure from a spec. NOT a publishable SDK package — a structural starting point.

根据规范搭建客户端代码结构。注意： 生成的并非可发布的SDK包，仅为结构起点。

SDK Steps

SDK搭建步骤

Parse spec — Extract endpoints, schemas, auth requirements
Group by resource — Organize endpoints into logical client modules
Generate client skeleton — Method stubs with typed parameters and return types
Auth integration — Wire auth mechanism into client constructor
Error handling — Map API error codes to client exceptions
Usage examples — One example per resource showing common operations

解析规范 — 提取端点、schema、认证需求
按资源分组 — 将端点组织为逻辑客户端模块
生成客户端框架 — 包含类型化参数与返回类型的方法存根
认证集成 — 在客户端构造函数中集成认证机制
错误处理 — 将API错误码映射为客户端异常
使用示例 — 每个资源提供一个展示常见操作的示例

Scripts

脚本

Script	Purpose	Run When
`scripts/api-spec-validator.py`	Validate OpenAPI 3.x for completeness and best practices	Design, Spec, Review
`scripts/api-endpoint-matrix.py`	Extract endpoint inventory from spec	Review, Version, SDK
`scripts/compat-checker.py`	Compare two specs for breaking changes	Compat

脚本	用途	运行时机
`scripts/api-spec-validator.py`	验证OpenAPI 3.x的完整性与最佳实践	设计、规范生成、评审
`scripts/api-endpoint-matrix.py`	从规范中提取端点清单	评审、版本管理、SDK搭建
`scripts/compat-checker.py`	对比两个规范的破坏性变更	兼容性分析

Script Invocation

脚本调用方式

bash

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>

All scripts output JSON to stdout, warnings to stderr.

bash

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输出到标准输出，警告信息输出到标准错误输出。

Reference File Index

参考文件索引

File	Content	Read When
`references/rest-conventions.md`	REST best practices, HTTP methods, status codes, naming, pagination, rate limiting	Design, Spec, Review (REST)
`references/graphql-patterns.md`	GraphQL schema design, query patterns, error handling, subscriptions	Design, Spec, Review (GraphQL)
`references/grpc-patterns.md`	gRPC service patterns, proto design, streaming, error codes	Design, Spec, Review (gRPC)
`references/versioning-strategies.md`	URL vs header vs query versioning, deprecation, backward compat checklist	Version, Compat
`data/http-conventions.json`	HTTP method semantics reference data	Scripts
`data/status-codes.json`	HTTP status code guide reference data	Scripts

Do not load all references at once. Load only what the detected protocol and active mode require.

文件	内容	读取时机
`references/rest-conventions.md`	REST最佳实践、HTTP方法、状态码、命名、分页、限流	设计、规范生成、评审（REST）
`references/graphql-patterns.md`	GraphQL schema设计、查询模式、错误处理、订阅	设计、规范生成、评审（GraphQL）
`references/grpc-patterns.md`	gRPC服务模式、proto设计、流处理、错误码	设计、规范生成、评审（gRPC）
`references/versioning-strategies.md`	URL/请求头/查询参数版本管理对比、弃用、向后兼容性检查清单	版本管理、兼容性分析
`data/http-conventions.json`	HTTP方法语义参考数据	脚本
`data/status-codes.json`	HTTP状态码指南参考数据	脚本

请勿一次性加载所有参考文件。仅加载检测到的协议与当前模式所需的文件。

Critical Rules

关键规则

Always detect protocol before entering any mode — never assume REST without evidence
If protocol is ambiguous, ask the user — do not guess
Generated specs must pass
```
api-spec-validator.py
```
before presenting to user
Every endpoint must have at least one error response defined (4xx or 5xx)
Never design APIs without pagination for list endpoints returning collections
Breaking changes in compat mode must include remediation suggestions
SDK mode produces structural scaffolds only — never claim the output is production-ready
Use the canonical vocabulary consistently — "spec" not "swagger", "endpoint" not "route"
All specs target OpenAPI 3.1 — do not generate Swagger 2.0 or OpenAPI 3.0
NOT for MCP servers (use mcp-creator) or frontend API client code

进入任何模式前必须先检测协议 — 无证据时切勿默认使用REST
若协议模糊不清，询问用户 — 切勿猜测
生成的规范必须通过
```
api-spec-validator.py
```
验证后再呈现给用户
每个端点必须至少定义一个错误响应（4xx或5xx）
返回集合的列表端点必须设计分页机制
兼容性分析模式中的破坏性变更必须包含修复建议
SDK模式仅生成结构框架 — 切勿声称输出可直接用于生产环境
统一使用标准术语 — 用“spec”而非“swagger”，用“endpoint”而非“route”
所有规范均以OpenAPI 3.1为目标 — 请勿生成Swagger 2.0或OpenAPI 3.0
不适用于MCP服务器（请使用mcp-creator）或前端API客户端代码

Scope Boundaries

范围边界

IS for:

Designing new REST, GraphQL, or gRPC APIs from requirements
Generating OpenAPI specs from existing code
Reviewing and auditing API designs
Versioning strategy and deprecation planning
Breaking change analysis between spec versions
Scaffolding client code structure

NOT for:

MCP server APIs (use
```
/mcp-creator
```
)
Frontend API client implementations
API gateway configuration
Runtime API testing or load testing
Database schema design (use
```
/database-architect
```
)

适用场景：

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

不适用场景：

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