[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"pack-detail-api-design-autodoc-es":3,"seo:pack:api-design-autodoc:es":92},{"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":91},"api-design-autodoc","🔌","#0EA5E9","new","Nuevo · esta semana","Pack de Diseño de API + Documentación Automática","Nueve selecciones para ingenieros diseñando APIs REST o GraphQL con IA en el loop — agentes de diseño spec-first, fuentes de verdad type-driven, diff de cambios incompatibles, generación de SDKs cliente, render interactivo de referencia y un cliente API real para pruebas end-to-end.",[16,28,36,43,51,61,67,74,81],{"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精选",28,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",26,{"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",43,{"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",44,"script","Script",{"id":62,"uuid":63,"slug":64,"title":65,"description":66,"author_name":57,"view_count":50,"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.",{"id":68,"uuid":69,"slug":70,"title":71,"description":72,"author_name":49,"view_count":73,"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.",176,{"id":75,"uuid":76,"slug":77,"title":78,"description":79,"author_name":57,"view_count":80,"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":82,"uuid":83,"slug":84,"title":85,"description":86,"author_name":87,"view_count":88,"vote_count":24,"lang_type":25,"type":89,"type_label":90},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":93,"pageKey":8,"locale":25,"title":94,"metaDescription":95,"h1":96,"tldr":97,"bodyMarkdown":98,"faq":99,"schema":115,"internalLinks":121,"citations":134,"wordCount":147,"generatedAt":148},"pack","API Design + Auto-Doc Pack — 9 Picks for Spec-First REST & GraphQL Builders","API Designer agent, API Architect, GraphQL Architect, TypeSpec, oasdiff, Kiota, Swagger UI, Insomnia, reShapr. Nine tools so AI agents help you design APIs, write OpenAPI specs, guard against breaking changes, generate SDKs, and render docs — installed in deliberate order with the tradeoffs spelled out.","API Design + Auto-Doc Pack — Nine Picks That Make Spec-First Workflows Actually Stick","A working API engineer's rig for letting AI agents design, spec, validate, generate SDKs, render docs, and test — without the contract drifting from reality. Design agents first, then a typed source of truth, then breaking-change diff, then client gen, then reference docs, then a real API client. Opinionated install order, no fabricated stats.","## What's in this pack\n\nAudience: you design **REST or GraphQL APIs** for a living. The contract you ship today gets consumed by a dozen client teams, an SDK auto-generator, a doc site, and an LLM that's writing client code based on whatever your OpenAPI spec says. You already have an AI in your editor. The thing it's still bad at is keeping all those surfaces **in sync as the API evolves** — design intent in one place, spec in another, generated SDK third, docs fourth, and three of them silently disagree by Friday.\n\nThis pack is nine tools that close that gap. Every pick is **operable by an agent (Claude Code skill, MCP server, or CLI an agent can drive)**, not just a library you could already npm-install. Six buckets in install order: design → spec source → validate → SDK gen → docs → test.\n\n## Install in this order\n\nOrder matters. Each tier produces the input the next tier needs.\n\n1. **Claude Code Agent: API Designer** (id 4287) — start here for greenfield work. A Claude Code agent that takes a feature description and proposes endpoints, payload shapes, status codes, pagination, error models. Read-only, no spec yet — this is the thinking step that prevents \"agent invents three competing pagination patterns by Wednesday.\"\n2. **Claude Code Agent: API Architect** (id 50) — heavier-weight cousin focused on REST + GraphQL system design across multiple resources, versioning strategy, auth scope shape, rate-limit semantics. Use when the feature isn't one endpoint but a whole resource model.\n3. **Claude Code Agent: GraphQL Architect** (id 4270) — GraphQL-specific. Schema design (types, interfaces, unions), N+1 prevention via batching, federation boundaries. Skip if you're 100% REST; install if any service in the org speaks GraphQL.\n4. **TypeSpec** (id 4194) — the typed source of truth. Microsoft's API description language that compiles to OpenAPI 3, JSON Schema, Protobuf. Writing TypeSpec instead of hand-editing 3000-line OpenAPI YAML is the single highest-leverage move in this stack — the agent reads + writes TypeSpec correctly far more often than it edits raw OpenAPI without breaking it.\n5. **oasdiff** (id 3215) — breaking-change diff CLI for OpenAPI specs. Run on every PR that touches the spec, gate merges on \"no breaking changes unless major version bump.\" This is what stops the AI from quietly renaming a field and shipping a P1 on Monday.\n6. **Kiota** (id 3189) — Microsoft's OpenAPI client generator. Same family as TypeSpec, generates idiomatic clients in C#, Go, Java, Python, TypeScript, Ruby, PHP. Faster + cleaner output than legacy generators for most contemporary specs.\n7. **Swagger UI** (id 2341) — interactive reference rendering. The de-facto \"try it out\" docs. Plain HTML + JS, no SaaS, drops into any static site. Pair with your TypeSpec → OpenAPI build.\n8. **Insomnia** (id 1918) — open-source API client for REST, GraphQL, gRPC. End-to-end testing surface. Use to manually verify the generated SDK actually talks to your service and the docs match what shipped.\n9. **reShapr** (id 3641) — turn OpenAPI into MCP tools, no-code. Now your own API is callable by Claude\u002FCodex\u002FCursor as MCP tools, which means the next AI agent your customer runs can drive your API directly. This is the part most teams skip and then wonder why competitors' APIs feel \"AI-native.\"\n\n## How they fit together\n\n```\n         ┌────────────────────────┐\n         │  Designer \u002F Architect  │  ← \"design this feature\"\n         │   agents (4287, 50)    │     (talks, no spec yet)\n         │   GraphQL Architect    │\n         │       (4270)           │\n         └───────────┬────────────┘\n                     │ endpoint + payload plan\n                     ▼\n         ┌────────────────────────┐\n         │  TypeSpec (4194)       │  ← typed source of truth\n         │  compiles to OpenAPI \u002F │\n         │  JSON Schema \u002F Protobuf│\n         └───────────┬────────────┘\n                     │ openapi.yaml\n                     ▼\n   ┌─────────────────┴─────────────────┐\n   │  oasdiff (3215) gates PR merges   │  ← breaking-change diff\n   └─────────────────┬─────────────────┘\n                     │ (safe spec)\n   ┌──────────┬──────┴──────┬──────────┐\n   ▼          ▼             ▼          ▼\n  Kiota   Swagger UI    reShapr     Insomnia\n  (3189)    (2341)      (3641)      (1918)\n  SDK gen   docs site   MCP tools   end-to-end test\n```\n\nThe loop that matters: **Design agent drafts → TypeSpec encodes the design as types → oasdiff guards the contract → SDK gen + docs + MCP wrapper + test client all consume the same spec.** Skip the typed source of truth and every downstream tier starts drifting. Skip oasdiff and the agent eventually makes a breaking change you didn't notice until a client breaks.\n\n## Tradeoffs you'll hit\n\n- **API Designer vs API Architect** — Designer (4287) is endpoint-level (\"how should I shape this resource\"). Architect (50) is system-level (\"how do these eight resources relate, version, authenticate\"). Greenfield single feature → Designer. New service or major-version redesign → Architect. Running both on the same prompt doubles the text and halves the signal.\n- **TypeSpec vs hand-written OpenAPI** — Hand-written wins if your team already has 5000 lines of curated OpenAPI and a stable spec. TypeSpec wins if you're starting fresh or your agent keeps producing invalid YAML when it edits the spec. The migration cost is real; plan for a week per service.\n- **Kiota vs OpenAPI Generator** — Kiota is newer, smaller surface, cleaner output, narrower language support. OpenAPI Generator (covered in the Tech Writer pack) is older, 50+ languages, less idiomatic output. Pick Kiota for contemporary stacks; OpenAPI Generator if you need clients in Ruby, Crystal, or Elixir.\n- **Swagger UI vs hosted doc platforms** — Swagger UI is free, static, runs nowhere. Hosted platforms (Stoplight, Readme, Mintlify) are slicker but they're a SaaS dependency. Start with Swagger UI; only upgrade when your DX team has a budget and a reason.\n- **Insomnia vs Postman** — Insomnia is open-source and local-first. Postman is the incumbent with cloud sync and team features. If your team is small and you don't need shared collections in the cloud, Insomnia is the cleaner pick — no account required, no telemetry, exports as plain JSON you can git-commit.\n- **reShapr vs writing MCP server by hand** — Hand-writing an MCP server gives you full control over tool naming, descriptions, and behavior. reShapr generates one from your OpenAPI in minutes but treats every endpoint as a tool, which can produce hundreds of tools when you wanted twenty. Start with reShapr to prove the value, then hand-curate if your API surface is large.\n\n## Common pitfalls\n\n- **Letting design agents invent the spec directly** — both Designer (4287) and Architect (50) will happily output OpenAPI YAML when asked. Resist. Get them to output a structured design doc first, then translate to TypeSpec, then compile. Skipping the structured-doc step makes the spec un-reviewable by humans.\n- **Skipping oasdiff because \"we'll catch it in code review\"** — you won't. The diff between v1 and v2 of a 3000-line spec is unreviewable by eye. Wire oasdiff into CI, gate merges on it, accept the friction.\n- **Generating SDKs into your service repo** — keep generated client code in a separate repo or `client-sdks\u002F` directory. Mixing service code with generated client code makes the build graph confusing and the agent eventually edits the wrong file.\n- **Treating Swagger UI as the only doc surface** — \"try it out\" docs are necessary but not sufficient. Pair with prose: getting-started guide, auth walkthrough, error catalog. The Tech Writer pack covers that side.\n- **Exposing your whole API as MCP tools without scoping** — reShapr (3641) makes it easy to expose 200 endpoints as 200 tools. Most agents start choking on tool selection past ~50 tools. Curate which endpoints become MCP tools; not every CRUD endpoint deserves to be one.",[100,103,106,109,112],{"q":101,"a":102},"Why TypeSpec instead of writing OpenAPI directly?","Two reasons. One, OpenAPI YAML is a serialization format, not a language meant for humans — once a spec passes ~1000 lines, hand-editing it without breaking validity is a constant low-grade tax. TypeSpec is a real language with imports, decorators, generics, and IDE support; the same API takes about a third the lines. Two, AI agents read and write TypeSpec correctly far more often than they edit OpenAPI without introducing schema errors. If you're starting fresh or the agent keeps breaking your spec, switching to TypeSpec pays back in two weeks.",{"q":104,"a":105},"Three design agents (4287, 50, 4270) — do I need all of them?","Probably not on the same project. API Designer (4287) is per-feature: shape this one resource. API Architect (50) is per-service: lay out the whole resource model. GraphQL Architect (4270) is GraphQL-only. A REST-only team building one feature uses just Designer. A team starting a new service in GraphQL uses Architect + GraphQL Architect. Stacking all three on a single prompt produces overlapping advice and zero extra signal.",{"q":107,"a":108},"Does oasdiff actually catch breaking changes the agent introduces?","Yes, and that's the entire point. The most common AI failure mode in spec work is renaming a field (`user_id` → `userId`), changing a required field to optional or vice versa, removing an enum value, or narrowing a response type. All of these are formally breaking, all of them slip past human review when the diff is large, and all of them are exactly what oasdiff is built to flag. Wire it into CI, fail the build on breaking changes unless the PR title says `BREAKING:`, and the class of incidents drops to near zero.",{"q":110,"a":111},"Why include reShapr — isn't MCP a separate concern from API design?","It used to be. In 2026 it isn't. Your API has two kinds of callers now: developers writing code, and AI agents calling tools. Designing only for the first set is a regression. reShapr (3641) turns your existing OpenAPI into MCP tools without rewriting anything, so the same contract serves both audiences. The pack treats it as the last install step because the value only shows up once the first eight are solid — but it does belong in the same rig.",{"q":113,"a":114},"Can one Claude Code session run this whole pack, or do I need a multi-agent setup?","One session is fine. The four 'agents' in this pack (API Designer, API Architect, GraphQL Architect, plus whichever Backend Architect you might add from the Backend pack) are Claude Code subagents — they install into the same session and switch in based on the task. TypeSpec, oasdiff, Kiota, Swagger UI, Insomnia, and reShapr are CLIs or local tools that any agent can drive via Bash. There's no multi-agent framework requirement; the orchestration is just your normal task flow with the right specialist agent in scope.",{"@context":116,"@type":117,"name":118,"description":119,"numberOfItems":120,"inLanguage":25},"https:\u002F\u002Fschema.org","ItemList","API Design + Auto-Doc Pack","Nine Claude Code agents and CLIs curated for engineers designing REST and GraphQL APIs — covering design, typed spec source, breaking-change diff, SDK generation, interactive docs, and end-to-end testing in deliberate install order.",9,[122,126,130],{"url":123,"anchor":124,"reason":125},"\u002Fen\u002Fai-tools-for\u002Fagents","Claude Code subagents directory","API Designer, API Architect, and GraphQL Architect live in the broader agents catalog",{"url":127,"anchor":128,"reason":129},"\u002Fen\u002Ftopics","Other topic packs","Adjacent packs cover backend engineering, tech writing, and frontend AI tooling",{"url":131,"anchor":132,"reason":133},"\u002Fen\u002Fai-tools-for\u002Fmcp","Browse all MCP servers","reShapr generates MCP tools from OpenAPI — the catalog has more MCP servers to compose with",[135,139,143],{"claim":136,"source_name":137,"source_url":138},"TypeSpec is a language for describing cloud service APIs that emits OpenAPI 3, JSON Schema, and Protobuf","TypeSpec official docs","https:\u002F\u002Ftypespec.io\u002F",{"claim":140,"source_name":141,"source_url":142},"oasdiff is a CLI that detects breaking changes between OpenAPI specifications","oasdiff GitHub","https:\u002F\u002Fgithub.com\u002Foasdiff\u002Foasdiff",{"claim":144,"source_name":145,"source_url":146},"Kiota generates API clients for HTTP REST APIs described by OpenAPI","Kiota Microsoft Learn","https:\u002F\u002Flearn.microsoft.com\u002Fen-us\u002Fopenapi\u002Fkiota\u002Foverview",920,"2026-05-22T00:00:00Z"]