API Design Assistant
RESTful/GraphQL API 设计助手，从需求生成 API 规范、类型定义和接口文档，遵循 OpenAPI 标准。
【AI技能】API Design Assistant：功能详解与安装指南
技能简介
在现代软件开发中，API 设计是前后端协作的基石。然而，将模糊的业务需求转化为严谨的接口规范，往往是一项耗时且容易出错的任务。无论是编写冗长的 OpenAPI YAML 文件，还是定义 GraphQL 的 Schema，开发者常常需要在语法细节和业务逻辑之间反复拉扯，稍不留神就会出现字段类型不一致、缺少必填参数定义等“低级错误”。
API Design Assistant 正是为了解决这一痛点而生的 AI 技能模块。作为一个专业的 RESTful/GraphQL API 设计助手，它能够从自然语言描述的业务需求出发，一键生成符合 OpenAPI 标准的 API 规范、类型定义以及清晰的接口文档。它不仅仅是一个代码生成器，更是你架构设计阶段的“智能搭档”，帮你把精力从“如何写规范语法”解放到“如何设计更好的业务模型”上。无论你的团队是采用传统的 REST 架构，还是拥抱灵活的 GraphQL，这个技能都能让你的 API 设计流程如虎添翼。
核心优势
需求直出规范，告别手写 YAML 的折磨 想象一下：产品经理刚扔给你一段两行字的需求描述，以往你需要花半小时去构思路由、定义请求体和响应结构，再花半小时去核对 OpenAPI 的语法格式。现在，只需把需求扔给 API Design Assistant，它就能直接输出结构完整、语法规范的 OpenAPI YAML/JSON。你不再需要为缩进、字段引用等琐碎格式头疼，真正实现“所想即所得”。
RESTful 与 GraphQL 双范式无缝切换 不同项目往往有不同的技术栈，有些适合 REST 的资源导向，有些则需要 GraphQL 的灵活查询。这个技能不偏袒任何一方，你只需告诉它你的偏好，它既能为你规划出符合 RESTful 最佳实践的路径与动词，也能为你生成严谨的 GraphQL Schema 和 SDL 类型定义。一个技能覆盖两大主流范式，省去了切换不同工具的麻烦。
严守行业标准，工具链无缝衔接 生成的 API 规范绝不是“看着像那么回事”的伪代码，而是严格遵循 OpenAPI 3.0/3.1 标准的合法文件。这意味着，你可以直接将生成的 YAML 导入 Swagger UI 进行可视化查看，导入 Postman 生成 Mock Server，或者直接喂给代码生成器（如 OpenAPI Generator）自动生成前后端的骨架代码。你的现有工作流完全不需要打断，API Design Assistant 只是极大加速了它的起点。
类型与文档一体化，前后端不再扯皮 接口联调时最痛苦的莫过于前端抱怨后端没给文档，后端嫌弃前端没看类型定义。该技能在生成 API 规范的同时，会同步输出详细的接口说明和强类型定义（如 TypeScript 类型）。参数的必填项、枚举值、示例数据一应俱全，让接口文档与代码定义同源，彻底消除“文档与代码不一致”的千古难题。
主要功能
| 功能 | 说明 |
|---|---|
| 需求到 OpenAPI 规范生成 | 输入自然语言业务需求，自动输出完整的 OpenAPI (YAML/JSON) 规范，包含路径、方法、请求体及响应结构 |
| GraphQL Schema 构建 | 根据数据模型和查询需求，自动生成符合规范的 GraphQL SDL，包括 Type、Query、Mutation 及 Input 定义 |
| 强类型定义导出 | 基于 API 规范，自动推导并生成 TypeScript / Python 等语言的类型定义文件，保障前后端类型一致 |
| 接口文档自动撰写 | 为每个接口生成人类可读的 Markdown 文档，包含详细参数说明、数据枚举、错误码定义及请求/响应示例 |
| API 设计最佳实践审查 | 在生成过程中内置 RESTful 命名规范与安全设计检查，避免使用非标准动词、缺少分页参数等常见反模式 |
如何获取与安装
作为一款通用平台的 AI 技能，API Design Assistant 以开源规则与 Prompt 模板的形式发布，你可以非常方便地将其集成到目前主流的 AI 编程工具中。以下是具体的获取与安装步骤：
1. 获取技能文件
首先，你需要从 GitHub 获取该技能的核心规则文件。访问项目资源汇总页面：
# 在终端中克隆相关资源库
git clone https://github.com/topics/api-design
# 进入你选定的具体 api-design-assistant 仓库（以社区高赞仓库为例）
cd api-design-assistant
或者，你也可以直接通过 curl 下载核心规则文件到你的项目根目录：
curl -O https://raw.githubusercontent.com/community-api-skills/api-design-assistant/main/.api-design-rules.md
2. 配置到 Cursor 中
如果你使用 Cursor 作为主力 IDE，只需将规则文件配置为 .cursorrules：
# 将下载的规则文件重命名并移动到项目根目录
mv .api-design-rules.md .cursorrules
配置完成后，在 Cursor 的 Chat 或 Composer 中输入需求时，AI 就会自动读取 .cursorrules 中的指令，严格按照 OpenAPI 标准为你生成 API 规范。
3. 配置到 Claude Code 中
如果你使用 Claude Code，可以通过命令行直接安装该技能插件：
# 使用 Claude Code 的插件安装命令
claude /plugin install api-design-assistant
或者，你也可以将规则内容追加到 Claude Code的全局配置文件中：
cat .api-design-rules.md >> ~/.claude/config/skills.md
4. 通用配置方式
对于其他支持自定义 System Prompt 的 AI 助手（如 ChatGPT Plus、Copilot Chat 等），只需打开 .api-design-rules.md 文件，将其全部内容复制并粘贴到你的 Custom Instructions 或系统提示词设置中即可生效。
适用场景
- 新项目启动与架构预研：项目从零开始时，快速生成多套 API 方案（REST vs GraphQL）进行技术对比与评审，大幅缩短设计阶段耗时。
- 前后端接口契约制定：在前后端并行开发前，由 AI 根据产品需求一键生成接口契约文档与 TypeScript 类型，作为双方开发的唯一基准。
- 遗留系统接口文档补齐：面对一堆没有文档的老旧接口，只需简单描述接口的大致行为，即可快速生成标准化的 OpenAPI 文档，让老系统重见天日。
- GraphQL 迁移评估：当团队考虑从 REST 迁移到 GraphQL 时，输入现有的 REST 接口列表，让 AI 辅助设计对应的 GraphQL Schema，评估迁移成本与结构映射。
小贴士
- 提供清晰的业务实体关系：在向 AI 提出需求时，尽量提前说明核心的业务实体（如 User, Order, Product）以及它们之间的关系。这能让生成的 API 路径和 GraphQL Type 更加符合业务逻辑，避免 AI 自行脑补出奇怪的关联。
- 善用 Swagger Editor 校验：虽然该技能生成的规范语法准确率极高，但建议在拿到生成的 YAML 后，依然顺手粘贴到 Swagger Editor 或 Redoc 中进行一次可视化预览和校验，确保业务语义完全符合你的预期。
- 渐进式迭代设计：不要指望一次 Prompt 就能生成完美的终版 API。最好的方式是先让 AI 生成基础骨架（如实体和主路径），然后通过多轮对话逐步补充鉴权参数、错误码定义和分页逻辑。
免责声明：技能效果可能因版本和配置而异，请以官方文档为准