openapi-from-zod
Generating an OpenAPI spec from existing Zod schemas instead of hand-writing or duplicating one. Use when a TypeScript API already validates requests/responses with Zod and needs published API docs, a
SKILL.md.claude/skills/openapi-from-zod/SKILL.md
GitHubOpenAPI from Zod
If request/response shapes are already defined as Zod schemas (this is exactly the
packages/shared-style pattern this template's example app uses), don't hand-write a
second, parallel OpenAPI document — generate it from the schemas that are already the
source of truth. A hand-maintained spec drifts from the code the first time someone
changes a schema and forgets the doc; a generated one can't drift.
Picking a library
- Zod v4 project →
zod-openapi. Attaches OpenAPI metadata with Zod's own.meta()(noextendZodWithOpenApistep, no parallel.openapi()method to remember) and produces 3.1.x documents via a singlecreateDocument()call. This is the lower-friction default for anything on Zod v4. - Zod v3 project →
@asteasolutions/zod-to-openapi. RequiresextendZodWithOpenApi(z)once at startup, then aOpenAPIRegistryto.register()schemas and.registerPath()per route before generating withOpenApiGeneratorV31. More ceremony, but it's the established option pre-v4. - Only need JSON Schema, not a full OpenAPI document (e.g. feeding a schema to an
LLM tool-use definition or a non-HTTP validator) →
zod-to-json-schema— skip OpenAPI's request/response/path envelope entirely.
Check package.json/lockfile for the installed Zod major version before picking —
don't assume; the two OpenAPI libraries above are not interchangeable.
Where metadata belongs
Add description/example (and id for anything that should become a reusable
#/components/schemas/* ref instead of being inlined everywhere it's used) directly
on the shared schema definitions, not on ad-hoc copies at each call site. If a schema
is already exported from a shared package for both server validation and client
typing, the OpenAPI metadata is one more thing that schema owns — keep it in the same
file as the schema, not scattered across route handlers.
Generating and keeping it current
- Generate into a build/output directory (e.g.
docs/openapi.json), not by hand- editing the generated file — same discipline as.claude/code-graph/graph.jsonin this template: it's a cache of the schemas, not something to diverge from them. - Wire generation into a script (
scripts/generate-openapi.tsor equivalent) rather than a one-off REPL session, so it's re-run — and the output re-committed or re-published — every time a schema changes, not just once at setup. - If the spec is published (a docs site, a client-generation pipeline), treat a
schema change that alters the generated spec's shape the same way
api-design's versioning guidance treats any other breaking API change — this is a good moment to apply that skill's rules, not a separate concern. - CI can diff the freshly generated spec against the committed one and fail if they disagree, catching a schema change that someone forgot to regenerate docs for before merging — worth adding once the generation script exists.