API 设计 + 自动文档套件

这个 pack 包含什么

受众：你以设计 REST 或 GraphQL API 为生。你今天发出去的契约要被十几个客户端团队消费、被 SDK 自动生成器消费、被文档站消费、还被一个根据你 OpenAPI spec 写客户端代码的 LLM 消费。编辑器里已经有 AI。它现在还做不好的事情是：让所有这些面在 API 演进时保持同步 — 设计意图在一处、spec 在另一处、生成的 SDK 在第三处、文档在第四处，到了周五其中三个已经悄悄不一致了。

这个 pack 9 个工具就是为这个缺口设计的。每一个都可以被 agent 直接操作（Claude Code skill、MCP server，或者 agent 能驱动的 CLI），不是又一个你 npm install 就能装的库。六层按顺序：设计 → spec 源 → 验证 → SDK 生成 → 文档 → 测试。

推荐安装顺序

顺序很重要。每一层产出下一层需要的输入。

1. Claude Code Agent: API Designer（id 4287）— 全新项目从这里开始。一个 Claude Code agent，吃功能描述，吐出端点、payload 形状、状态码、分页、错误模型。只动嘴不出 spec — 这是「想清楚」的环节，避免「agent 在周三之前发明了三套互相打架的分页方案」。
2. Claude Code Agent: API Architect（id 50）— 重量级的同门，专注 REST + GraphQL 跨多个资源的系统设计、版本策略、auth scope 形状、限流语义。需求不是一个端点而是整个资源模型时上。
3. Claude Code Agent: GraphQL Architect（id 4270）— GraphQL 专属。schema 设计（type / interface / union）、用 batching 防 N+1、联邦边界。100% REST 团队跳过；组织里有任何服务讲 GraphQL 就装上。
4. TypeSpec（id 4194）— 类型化的真相源。微软的 API 描述语言，编译到 OpenAPI 3 / JSON Schema / Protobuf。写 TypeSpec 而不是手编 3000 行 OpenAPI YAML 是这套里单点杠杆最高的一招 — agent 读写 TypeSpec 的正确率远高于直接改原始 OpenAPI 不出错的概率。
5. oasdiff（id 3215）— OpenAPI spec 的 breaking-change diff CLI。每个动 spec 的 PR 都跑一遍，merge 卡「不是 major version bump 不许有 breaking change」。这就是阻止 AI 悄悄重命名一个字段、然后周一发出去一个 P1 的那道闸门。
6. Kiota（id 3189）— 微软的 OpenAPI 客户端生成器。和 TypeSpec 同门，生成 C# / Go / Java / Python / TypeScript / Ruby / PHP 的地道客户端。对现代 spec 而言，速度和输出质量都比老一辈生成器更好。
7. Swagger UI（id 2341）— 交互式 reference 渲染。事实标准的「Try it out」文档。纯 HTML + JS，没 SaaS，丢到任何静态站点都行。配 TypeSpec → OpenAPI 构建链使用。
8. Insomnia（id 1918）— 开源 API 客户端，支持 REST / GraphQL / gRPC。端到端测试面。用来手工验证生成出来的 SDK 真能跟你的服务说话、文档跟上线的内容对得上。
9. reShapr（id 3641）— 把 OpenAPI 变成 MCP tool，零代码。这一步之后，你自己的 API 就能被 Claude / Codex / Cursor 当作 MCP tool 调用 — 意味着你客户跑的下一个 AI agent 能直接驱动你的 API。大多数团队跳过这步，然后纳闷为啥竞争对手的 API 感觉更「AI 原生」。

它们怎么协同

         ┌────────────────────────┐
         │  Designer / Architect  │  ← 「设计这个功能」
         │   agents (4287, 50)    │     （只说话，还不出 spec）
         │   GraphQL Architect    │
         │       (4270)           │
         └───────────┬────────────┘
                     │ 端点 + payload 方案
                     ▼
         ┌────────────────────────┐
         │  TypeSpec (4194)       │  ← 类型化真相源
         │  编译到 OpenAPI /      │
         │  JSON Schema / Protobuf│
         └───────────┬────────────┘
                     │ openapi.yaml
                     ▼
   ┌─────────────────┴─────────────────┐
   │  oasdiff (3215) 卡 PR merge       │  ← breaking-change diff
   └─────────────────┬─────────────────┘
                     │ （安全的 spec）
   ┌──────────┬──────┴──────┬──────────┐
   ▼          ▼             ▼          ▼
  Kiota   Swagger UI    reShapr     Insomnia
  (3189)    (2341)      (3641)      (1918)
  SDK 生成  文档站      MCP tool    端到端测试

关键的闭环：设计 agent 起草 → TypeSpec 把设计编码成类型 → oasdiff 守住契约 → SDK 生成 + 文档 + MCP wrapper + 测试客户端都消费同一份 spec。 跳过类型化真相源，下游每一层都开始漂移。跳过 oasdiff，agent 早晚会做一个 breaking change，等客户出问题你才发现。

你会遇到的取舍

• API Designer vs API Architect — Designer（4287）是端点级（「这一个资源该长什么样」）。Architect（50）是系统级（「这 8 个资源怎么关联 / 版本化 / 鉴权」）。全新单个功能 → Designer。新服务或大版本重设计 → Architect。同一个 prompt 上叠两个 → 文本量乘 2、信号量减半。
• TypeSpec vs 手写 OpenAPI — 已经有 5000 行精心整理的 OpenAPI 和稳定 spec 的团队，手写赢。从零开始、或者 agent 老是把 spec 改成无效 YAML 的团队，TypeSpec 赢。迁移成本真存在；每个服务规划一周。
• Kiota vs OpenAPI Generator — Kiota 更新、面更小、输出更干净、支持语言更少。OpenAPI Generator（Tech Writer pack 里）更老、50+ 种语言、输出不太地道。现代栈选 Kiota；需要 Ruby / Crystal / Elixir 客户端选 OpenAPI Generator。
• Swagger UI vs 托管文档平台 — Swagger UI 免费、纯静态、不依赖任何后台。托管平台（Stoplight / Readme / Mintlify）更精致但是 SaaS 依赖。先用 Swagger UI；只有当 DX 团队有预算和理由时再升级。
• Insomnia vs Postman — Insomnia 开源、本地优先。Postman 是带云同步和团队功能的市场领导者。小团队、不需要云端共享 collection 的话，Insomnia 更干净 — 不用账号、没遥测、导出是能 git-commit 的纯 JSON。
• reShapr vs 手写 MCP server — 手写 MCP server 给你完全控制 tool 命名、描述、行为的能力。reShapr 几分钟从 OpenAPI 生一个出来，但是把每个端点都当成一个 tool —— 你想要 20 个，它给你 200 个。先用 reShapr 证明价值，API 面大了再手工裁剪。

常见踩坑

• 让设计 agent 直接发明 spec — Designer（4287）和 Architect（50）都很乐意按要求输出 OpenAPI YAML。别。让它们先输出结构化的设计文档，然后翻译成 TypeSpec，再编译。跳过结构化文档这一步，spec 会变成人审不动的黑盒。
• 「我们 code review 时会抓住的」所以跳过 oasdiff — 抓不住。3000 行 spec 的 v1 vs v2 diff 肉眼审不动。把 oasdiff 接到 CI 里，让它卡 merge，接受这点摩擦。
• 把生成的 SDK 写进服务仓库 — 生成的客户端代码放独立仓库或者 client-sdks/ 目录。服务代码和生成代码混在一起，构建图会变乱，agent 早晚改错文件。
• 把 Swagger UI 当成唯一的文档面 — 「Try it out」文档必要但不充分。要配散文：上手指南、auth 走读、错误目录。那部分是 Tech Writer pack 的活。
• 不做 scope 就把整个 API 暴露成 MCP tool — reShapr（3641）让你轻松把 200 个端点暴露成 200 个 tool。大多数 agent 在 50 个 tool 以上就开始噎住。要裁剪哪些端点变 MCP tool；不是每个 CRUD 端点都配。