Zod to OpenAPI

Quick answer: how do you convert Zod to OpenAPI?

Use a Zod to OpenAPI package when you need a complete Swagger/OpenAPI document with paths, operations, request bodies, responses, and reusable components. Use FrameworkKit when you need to inspect or copy OpenAPI-compatible schema components from Zod before adding a package workflow to your codebase.

Generate a full OpenAPI document from Zod

A full zod to openapi workflow has three layers: Zod schemas for runtime validation, OpenAPI metadata for schema names and examples, and route definitions for paths, methods, request bodies, responses, tags, and security.

import { OpenAPIRegistry, OpenApiGeneratorV3 } from "@asteasolutions/zod-to-openapi";
import { z } from "zod";

const registry = new OpenAPIRegistry();

const UserSchema = registry.register(
  "User",
  z.object({
    id: z.string().uuid(),
    email: z.string().email(),
  }),
);

registry.registerPath({
  method: "get",
  path: "/users/{id}",
  responses: {
    200: {
      description: "User response",
      content: {
        "application/json": {
          schema: UserSchema,
        },
      },
    },
  },
});

export const openApiDocument = new OpenApiGeneratorV3(registry.definitions).generateDocument({
  openapi: "3.0.3",
  info: { title: "Users API", version: "1.0.0" },
});

Components schemas from Zod

When your immediate need is a component schema, convert Zod to an OpenAPI-compatible schema object first. This is the safest way to review nullable fields, required keys, enums, arrays, and extra-property behavior before adding that schema under `components.schemas`.

Paths, request bodies, and responses

OpenAPI docs need more than schemas. Add each API path with method, params, query, request body, response content, status codes, operation IDs, tags, and auth metadata so Swagger UI and SDK generators understand the API surface.

• Use Zod schemas for request bodies and response bodies at the API boundary.
• Register route params and query params explicitly instead of hiding them in application code.
• Add stable operation IDs when the OpenAPI document will feed SDK generation.
• Keep examples representative, but avoid pasting secrets or production-only payloads into public docs.

OpenAPI 3.0 vs OpenAPI 3.1 for Zod

Choose OpenAPI 3.0 when your docs, gateway, or SDK generator expects `nullable: true`. Choose OpenAPI 3.1 when your tooling understands modern JSON Schema unions such as `type: ["string", "null"]`.

// OpenAPI 3.0 style
{ "type": "string", "nullable": true }

// OpenAPI 3.1 style
{ "type": ["string", "null"] }

Swagger UI and SDK generation

Once the document is generated, validate it before publishing it to Swagger UI, Redoc, Speakeasy, Stainless, OpenAPI Generator, or an API gateway. Treat generated docs as a contract, not just a prettier view of route code.

• Run OpenAPI validation in CI before publishing docs.
• Preview the generated document in Swagger UI or Redoc.
• Generate a small SDK/client fixture to catch operation ID and schema drift.
• Test valid, invalid, nullable, optional, and error response examples against the same Zod schemas.

When FrameworkKit fits the workflow

FrameworkKit is not a replacement for a route-aware zod to openapi package. It is useful before package setup, during schema review, or when a teammate needs a browser-only way to inspect the OpenAPI-compatible component shape.

Zod to OpenAPI workflow comparison

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

Zod to JSON Schema resources

FAQ

Related tools