[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"pack-detail-api-design-autodoc-zh":3,"seo:pack:api-design-autodoc:zh":93},{"code":4,"message":5,"data":6},200,"操作成功",{"pack":7},{"slug":8,"icon":9,"tone":10,"status":11,"status_label":12,"title":13,"description":14,"items":15,"install_cmd":92},"api-design-autodoc","🔌","#0EA5E9","new","本周新建","API 设计 + 自动文档套件","9 件套，给设计 REST \u002F GraphQL API 的工程师：spec-first 设计 agent、类型驱动的真相源、契约 breaking-change diff、客户端 SDK 生成、交互式 reference 渲染，以及做端到端测试的真 API 客户端。",[16,28,36,43,51,61,68,75,82],{"id":17,"uuid":18,"slug":19,"title":20,"description":21,"author_name":22,"view_count":23,"vote_count":24,"lang_type":25,"type":26,"type_label":27},4287,"1396c744-fae4-41b2-87d2-5dccc536502f","claude-code-agent-api-designer-1396c744","Claude Code Agent: API Designer","Use this agent when designing new APIs, creating API specifications, or refactoring existing API architecture for scalability and developer experience. Invoke when you need...","TokRepo精选",29,0,"en","skill","Skill",{"id":29,"uuid":30,"slug":31,"title":32,"description":33,"author_name":34,"view_count":35,"vote_count":24,"lang_type":25,"type":26,"type_label":27},50,"28978138-4b75-45c7-a5f2-01d2f7a3346c","claude-code-agent-api-architect-design-rest-graphql-apis-28978138","Claude Code Agent: API Architect — Design REST & GraphQL APIs","Claude Code agent for API design. REST endpoints, GraphQL schemas, authentication, rate limiting, versioning, and documentation.","Skill Factory",193,{"id":37,"uuid":38,"slug":39,"title":40,"description":41,"author_name":22,"view_count":42,"vote_count":24,"lang_type":25,"type":26,"type_label":27},4270,"72baddfa-8fc9-499c-869e-cbaff0af4790","claude-code-agent-graphql-architect-72baddfa","Claude Code Agent: Graphql Architect","Use this agent when designing or evolving GraphQL schemas across microservices, implementing federation architectures, or optimizing query performance in distributed graphs. Specif",30,{"id":44,"uuid":45,"slug":46,"title":47,"description":48,"author_name":49,"view_count":50,"vote_count":24,"lang_type":25,"type":26,"type_label":27},4194,"6080f271-52b6-11f1-9bc6-00163e2b0d79","typespec-define-apis-types-microsoft-6080f271","TypeSpec — Define APIs with Types by Microsoft","TypeSpec is an API definition language by Microsoft that lets you describe REST, OpenAPI, gRPC, and other API protocols using a concise, type-safe syntax. It generates OpenAPI specs, client SDKs, and server stubs from a single source of truth.","AI Open Source",48,{"id":52,"uuid":53,"slug":54,"title":55,"description":56,"author_name":57,"view_count":58,"vote_count":24,"lang_type":25,"type":59,"type_label":60},3215,"ad3d0523-cda7-4257-9bdb-023370d39c5a","oasdiff-openapi-breaking-change-diff-cli","oasdiff — OpenAPI Breaking-Change Diff CLI","oasdiff compares two OpenAPI specs and flags breaking changes with CI-friendly exit codes, so API refactors don’t silently ship incompatible contracts.","Script Depot",53,"script","Script",{"id":62,"uuid":63,"slug":64,"title":65,"description":66,"author_name":57,"view_count":67,"vote_count":24,"lang_type":25,"type":59,"type_label":60},3189,"61a95ca0-13fc-4498-a577-8fe56042e62d","kiota-generate-openapi-clients-anywhere","Kiota — Generate OpenAPI Clients Anywhere","Kiota is a CLI that generates strongly-typed API clients from any OpenAPI description, so your app doesn’t depend on a different SDK per service.",45,{"id":69,"uuid":70,"slug":71,"title":72,"description":73,"author_name":49,"view_count":74,"vote_count":24,"lang_type":25,"type":26,"type_label":27},2341,"bd2b2213-4384-11f1-9bc6-00163e2b0d79","swagger-ui-interactive-api-documentation-openapi-specs-bd2b2213","Swagger UI — Interactive API Documentation from OpenAPI Specs","A browser-based tool that renders OpenAPI specifications as interactive API documentation where developers can explore endpoints and execute requests directly.",177,{"id":76,"uuid":77,"slug":78,"title":79,"description":80,"author_name":57,"view_count":81,"vote_count":24,"lang_type":25,"type":59,"type_label":60},1918,"d4c71a18-3de3-11f1-9bc6-00163e2b0d79","insomnia-open-source-api-client-rest-graphql-grpc-d4c71a18","Insomnia — Open-Source API Client for REST, GraphQL & gRPC","Design, debug, and test APIs with a collaborative open-source client that supports REST, GraphQL, gRPC, and WebSocket protocols.",141,{"id":83,"uuid":84,"slug":85,"title":86,"description":87,"author_name":88,"view_count":89,"vote_count":24,"lang_type":25,"type":90,"type_label":91},3641,"47dff284-e7d8-5445-a48a-f4b1031f2ef5","reshapr-turn-openapi-into-mcp-tools-no-code","reShapr — Turn OpenAPI into MCP Tools (No-code)","reShapr turns REST\u002FGraphQL\u002FgRPC APIs into MCP tools with context control; verified 86★ and ships a CLI plus `reshapr run` to start the platform.","MCP Hub",58,"mcp","MCP","tokrepo install pack\u002Fapi-design-autodoc",{"pageType":94,"pageKey":8,"locale":95,"title":96,"metaDescription":97,"h1":98,"tldr":99,"bodyMarkdown":100,"faq":101,"schema":117,"internalLinks":123,"citations":136,"wordCount":149,"generatedAt":150},"pack","zh","API 设计 + 自动文档套件 — spec-first REST 和 GraphQL 工程师的 9 件套","API Designer agent \u002F API Architect \u002F GraphQL Architect \u002F TypeSpec \u002F oasdiff \u002F Kiota \u002F Swagger UI \u002F Insomnia \u002F reShapr。9 个工具让 AI agent 真正帮你设计 API、写 OpenAPI spec、防 breaking change、生 SDK、渲染文档 — 含推荐安装顺序和取舍说明。","API 设计 + 自动文档套件 — 让 spec-first 工作流真正落地的 9 件套","一个在职 API 工程师的 AI 战机配置：让 agent 设计、写 spec、做契约验证、生 SDK、渲染文档、跑测试 — 又不让契约脱离现实。先设计 agent，再类型化的真相源，再 breaking-change diff，再客户端生成，再 reference 文档，最后真的 API 客户端。安装顺序经过精心安排，全是真东西、没有编造的数字。","## 这个 pack 包含什么\n\n受众：你以设计 **REST 或 GraphQL API** 为生。你今天发出去的契约要被十几个客户端团队消费、被 SDK 自动生成器消费、被文档站消费、还被一个根据你 OpenAPI spec 写客户端代码的 LLM 消费。编辑器里已经有 AI。它现在还做不好的事情是：**让所有这些面在 API 演进时保持同步** — 设计意图在一处、spec 在另一处、生成的 SDK 在第三处、文档在第四处，到了周五其中三个已经悄悄不一致了。\n\n这个 pack 9 个工具就是为这个缺口设计的。每一个都**可以被 agent 直接操作**（Claude Code skill、MCP server，或者 agent 能驱动的 CLI），不是又一个你 `npm install` 就能装的库。六层按顺序：设计 → spec 源 → 验证 → SDK 生成 → 文档 → 测试。\n\n## 推荐安装顺序\n\n顺序很重要。每一层产出下一层需要的输入。\n\n1. **Claude Code Agent: API Designer**（id 4287）— 全新项目从这里开始。一个 Claude Code agent，吃功能描述，吐出端点、payload 形状、状态码、分页、错误模型。只动嘴不出 spec — 这是「想清楚」的环节，避免「agent 在周三之前发明了三套互相打架的分页方案」。\n2. **Claude Code Agent: API Architect**（id 50）— 重量级的同门，专注 REST + GraphQL 跨多个资源的系统设计、版本策略、auth scope 形状、限流语义。需求不是一个端点而是整个资源模型时上。\n3. **Claude Code Agent: GraphQL Architect**（id 4270）— GraphQL 专属。schema 设计（type \u002F interface \u002F union）、用 batching 防 N+1、联邦边界。100% REST 团队跳过；组织里有任何服务讲 GraphQL 就装上。\n4. **TypeSpec**（id 4194）— 类型化的真相源。微软的 API 描述语言，编译到 OpenAPI 3 \u002F JSON Schema \u002F Protobuf。写 TypeSpec 而不是手编 3000 行 OpenAPI YAML 是这套里**单点杠杆最高**的一招 — agent 读写 TypeSpec 的正确率远高于直接改原始 OpenAPI 不出错的概率。\n5. **oasdiff**（id 3215）— OpenAPI spec 的 breaking-change diff CLI。每个动 spec 的 PR 都跑一遍，merge 卡「不是 major version bump 不许有 breaking change」。这就是阻止 AI 悄悄重命名一个字段、然后周一发出去一个 P1 的那道闸门。\n6. **Kiota**（id 3189）— 微软的 OpenAPI 客户端生成器。和 TypeSpec 同门，生成 C# \u002F Go \u002F Java \u002F Python \u002F TypeScript \u002F Ruby \u002F PHP 的地道客户端。对现代 spec 而言，速度和输出质量都比老一辈生成器更好。\n7. **Swagger UI**（id 2341）— 交互式 reference 渲染。事实标准的「Try it out」文档。纯 HTML + JS，没 SaaS，丢到任何静态站点都行。配 TypeSpec → OpenAPI 构建链使用。\n8. **Insomnia**（id 1918）— 开源 API 客户端，支持 REST \u002F GraphQL \u002F gRPC。端到端测试面。用来手工验证生成出来的 SDK 真能跟你的服务说话、文档跟上线的内容对得上。\n9. **reShapr**（id 3641）— 把 OpenAPI 变成 MCP tool，零代码。这一步之后，你自己的 API 就能被 Claude \u002F Codex \u002F Cursor 当作 MCP tool 调用 — 意味着你客户跑的下一个 AI agent 能直接驱动你的 API。大多数团队跳过这步，然后纳闷为啥竞争对手的 API 感觉更「AI 原生」。\n\n## 它们怎么协同\n\n```\n         ┌────────────────────────┐\n         │  Designer \u002F Architect  │  ← 「设计这个功能」\n         │   agents (4287, 50)    │     （只说话，还不出 spec）\n         │   GraphQL Architect    │\n         │       (4270)           │\n         └───────────┬────────────┘\n                     │ 端点 + payload 方案\n                     ▼\n         ┌────────────────────────┐\n         │  TypeSpec (4194)       │  ← 类型化真相源\n         │  编译到 OpenAPI \u002F      │\n         │  JSON Schema \u002F Protobuf│\n         └───────────┬────────────┘\n                     │ openapi.yaml\n                     ▼\n   ┌─────────────────┴─────────────────┐\n   │  oasdiff (3215) 卡 PR merge       │  ← breaking-change diff\n   └─────────────────┬─────────────────┘\n                     │ （安全的 spec）\n   ┌──────────┬──────┴──────┬──────────┐\n   ▼          ▼             ▼          ▼\n  Kiota   Swagger UI    reShapr     Insomnia\n  (3189)    (2341)      (3641)      (1918)\n  SDK 生成  文档站      MCP tool    端到端测试\n```\n\n关键的闭环：**设计 agent 起草 → TypeSpec 把设计编码成类型 → oasdiff 守住契约 → SDK 生成 + 文档 + MCP wrapper + 测试客户端都消费同一份 spec。** 跳过类型化真相源，下游每一层都开始漂移。跳过 oasdiff，agent 早晚会做一个 breaking change，等客户出问题你才发现。\n\n## 你会遇到的取舍\n\n- **API Designer vs API Architect** — Designer（4287）是端点级（「这一个资源该长什么样」）。Architect（50）是系统级（「这 8 个资源怎么关联 \u002F 版本化 \u002F 鉴权」）。全新单个功能 → Designer。新服务或大版本重设计 → Architect。同一个 prompt 上叠两个 → 文本量乘 2、信号量减半。\n- **TypeSpec vs 手写 OpenAPI** — 已经有 5000 行精心整理的 OpenAPI 和稳定 spec 的团队，手写赢。从零开始、或者 agent 老是把 spec 改成无效 YAML 的团队，TypeSpec 赢。迁移成本真存在；每个服务规划一周。\n- **Kiota vs OpenAPI Generator** — Kiota 更新、面更小、输出更干净、支持语言更少。OpenAPI Generator（Tech Writer pack 里）更老、50+ 种语言、输出不太地道。现代栈选 Kiota；需要 Ruby \u002F Crystal \u002F Elixir 客户端选 OpenAPI Generator。\n- **Swagger UI vs 托管文档平台** — Swagger UI 免费、纯静态、不依赖任何后台。托管平台（Stoplight \u002F Readme \u002F Mintlify）更精致但是 SaaS 依赖。先用 Swagger UI；只有当 DX 团队有预算和理由时再升级。\n- **Insomnia vs Postman** — Insomnia 开源、本地优先。Postman 是带云同步和团队功能的市场领导者。小团队、不需要云端共享 collection 的话，Insomnia 更干净 — 不用账号、没遥测、导出是能 git-commit 的纯 JSON。\n- **reShapr vs 手写 MCP server** — 手写 MCP server 给你完全控制 tool 命名、描述、行为的能力。reShapr 几分钟从 OpenAPI 生一个出来，但是把每个端点都当成一个 tool —— 你想要 20 个，它给你 200 个。先用 reShapr 证明价值，API 面大了再手工裁剪。\n\n## 常见踩坑\n\n- **让设计 agent 直接发明 spec** — Designer（4287）和 Architect（50）都很乐意按要求输出 OpenAPI YAML。别。让它们先输出结构化的设计文档，然后翻译成 TypeSpec，再编译。跳过结构化文档这一步，spec 会变成人审不动的黑盒。\n- **「我们 code review 时会抓住的」所以跳过 oasdiff** — 抓不住。3000 行 spec 的 v1 vs v2 diff 肉眼审不动。把 oasdiff 接到 CI 里，让它卡 merge，接受这点摩擦。\n- **把生成的 SDK 写进服务仓库** — 生成的客户端代码放独立仓库或者 `client-sdks\u002F` 目录。服务代码和生成代码混在一起，构建图会变乱，agent 早晚改错文件。\n- **把 Swagger UI 当成唯一的文档面** — 「Try it out」文档必要但不充分。要配散文：上手指南、auth 走读、错误目录。那部分是 Tech Writer pack 的活。\n- **不做 scope 就把整个 API 暴露成 MCP tool** — reShapr（3641）让你轻松把 200 个端点暴露成 200 个 tool。大多数 agent 在 50 个 tool 以上就开始噎住。要裁剪哪些端点变 MCP tool；不是每个 CRUD 端点都配。",[102,105,108,111,114],{"q":103,"a":104},"为啥用 TypeSpec 而不是直接写 OpenAPI？","两个原因。一，OpenAPI YAML 是一个序列化格式，不是给人看的语言 — spec 一旦过 1000 行，手编不出错就是一个持续的低强度税。TypeSpec 是真正的语言：有 import、decorator、泛型、IDE 支持；同样的 API 大概只要三分之一的行数。二，AI agent 读写 TypeSpec 的正确率远高于改 OpenAPI 不引入 schema 错误的概率。如果你从零开始、或者 agent 老是把 spec 改坏，切到 TypeSpec 两周就回本。",{"q":106,"a":107},"三个设计 agent（4287 \u002F 50 \u002F 4270）都要装吗？","大概率不是同一个项目都装。API Designer（4287）是按功能维度：把这一个资源想清楚。API Architect（50）是按服务维度：把整个资源模型铺开。GraphQL Architect（4270）只针对 GraphQL。纯 REST 团队做单个功能 — 只用 Designer。新服务用 GraphQL — Architect + GraphQL Architect。一个 prompt 上叠三个 — 建议重叠、零增量信号。",{"q":109,"a":110},"oasdiff 真能抓住 agent 引入的 breaking change？","能，这正是要点。AI 做 spec 时最常见的失败模式：重命名字段（`user_id` → `userId`）、把必填改成可选或反过来、删除一个枚举值、把响应类型收窄。这些都是形式上的 breaking change，diff 大了肉眼审都漏，正好是 oasdiff 要标的东西。接到 CI 里、PR 标题没有 `BREAKING:` 就 fail，这类事故近乎归零。",{"q":112,"a":113},"为啥把 reShapr 也算进来 — MCP 不是跟 API 设计是两回事吗？","以前是。2026 年不是。你的 API 现在有两类调用方：写代码的开发者，和调 tool 的 AI agent。只为前者设计就是退步。reShapr（3641）不用重写任何东西，把你既有的 OpenAPI 变成 MCP tool，同一份契约同时服务两类受众。pack 把它放最后一步是因为价值只有前 8 步都稳了之后才显现 — 但它确实属于这套配置。",{"q":115,"a":116},"整套能用一个 Claude Code 会话跑完吗？还是要多 agent 系统？","一个就够。pack 里的四个「agent」（API Designer \u002F API Architect \u002F GraphQL Architect，加上 Backend pack 里可能拉来的 Backend Architect）都是 Claude Code 的 subagent — 它们装到同一个会话里，按任务自动切换。TypeSpec \u002F oasdiff \u002F Kiota \u002F Swagger UI \u002F Insomnia \u002F reShapr 是 CLI 或本地工具，任何 agent 都能通过 Bash 驱动。不需要多 agent 框架；编排就是你常规的任务流加上当前 scope 里合适的专家 agent。",{"@context":118,"@type":119,"name":13,"description":120,"numberOfItems":121,"inLanguage":122},"https:\u002F\u002Fschema.org","ItemList","为设计 REST 和 GraphQL API 的工程师精选的 9 个 Claude Code agent 和 CLI — 覆盖设计、类型化 spec 源、breaking-change diff、SDK 生成、交互式文档和端到端测试，含推荐安装顺序。",9,"zh-CN",[124,128,132],{"url":125,"anchor":126,"reason":127},"\u002Fzh\u002Fai-tools-for\u002Fagents","Claude Code subagent 目录","API Designer \u002F API Architect \u002F GraphQL Architect 都属于更大的 agent 目录",{"url":129,"anchor":130,"reason":131},"\u002Fzh\u002Ftopics","其它主题 pack","相邻 pack 涵盖后端工程、技术写作、前端 AI 工具等主题",{"url":133,"anchor":134,"reason":135},"\u002Fzh\u002Fai-tools-for\u002Fmcp","浏览全部 MCP server","reShapr 从 OpenAPI 生成 MCP tool — 目录里还有更多 MCP server 可以组合",[137,141,145],{"claim":138,"source_name":139,"source_url":140},"TypeSpec 是描述云服务 API 的语言，可生成 OpenAPI 3 \u002F JSON Schema \u002F Protobuf","TypeSpec 官方文档","https:\u002F\u002Ftypespec.io\u002F",{"claim":142,"source_name":143,"source_url":144},"oasdiff 是一个检测 OpenAPI 规范间 breaking change 的 CLI","oasdiff GitHub","https:\u002F\u002Fgithub.com\u002Foasdiff\u002Foasdiff",{"claim":146,"source_name":147,"source_url":148},"Kiota 为 OpenAPI 描述的 HTTP REST API 生成客户端","Kiota Microsoft Learn","https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fopenapi\u002Fkiota\u002Foverview",900,"2026-05-22T00:00:00Z"]