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

GitHub

OpenAPI 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() (no extendZodWithOpenApi step, no parallel .openapi() method to remember) and produces 3.1.x documents via a single createDocument() call. This is the lower-friction default for anything on Zod v4.
  • Zod v3 project → @asteasolutions/zod-to-openapi. Requires extendZodWithOpenApi(z) once at startup, then a OpenAPIRegistry to .register() schemas and .registerPath() per route before generating with OpenApiGeneratorV31. 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.json in this template: it's a cache of the schemas, not something to diverge from them.
  • Wire generation into a script (scripts/generate-openapi.ts or 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.