[opensourcedex]

zod-to-openapi is a free, open source api development & testing project written in TypeScript and released under MIT. It has 1,619 GitHub stars, 103 forks and 39 open issues, and was last pushed 5 days ago. On this registry it ranks #128 of 178 tracked projects in API Development & Testing, with 5 head-to-head comparisons available.

What is zod-to-openapi?

A TypeScript library from Astea Solutions that generates OpenAPI (Swagger) documentation directly from Zod schemas, for API developers and teams who already validate requests with Zod and do not want to maintain a second, hand-written specification.

What it is

zod-to-openapi is an MIT-licensed TypeScript library, published on npm as @asteasolutions/zod-to-openapi, that takes Zod schemas and produces an OpenAPI definition from them. It lives in the JavaScript and TypeScript ecosystem, alongside Zod itself and the OpenAPI tooling that consumes the generated documents. The library works by extending Zod: it adds an openapi method to Zod objects through extendZodWithOpenApi, and exposes a Registry for routes, webhooks and custom components plus a Generator that emits the final document. Because the same schema objects that validate incoming requests also carry the OpenAPI metadata, one definition serves both purposes.

The concrete problem it solves is duplication. The maintainers state they built the library because they use Zod for validation in their APIs and grew tired of maintaining a separate OpenAPI definition that had to be kept in sync with it. In practice that means a schema written once as Zod can be rendered into components/schemas and $ref entries in the generated YAML, while the original UserSchema and request.params objects continue to validate input at runtime. The specific thing it replaces is the manually written OpenAPI or Swagger specification file, which otherwise drifts out of step with validation rules whenever a field changes.

Key capabilities

  • Extends every Zod object with an openapi method that has three overloads: .openapi({ [key]: value }) to attach arbitrary OpenAPI fields such as example, .openapi(" ") to register the schema into components/schemas, and .openapi(" ", { [key]: value }) to do both at once.
  • Requires a single call to extendZodWithOpenApi, made in a common entry point such as index.ts or app.ts; the README notes that the file may need to be marked as having side effects when tree-shaking with Webpack.
  • Provides a Registry with registry.registerPath({ method, path, summary, request, responses }) for defining paths, and also covers routes, webhooks and custom components.
  • Provides a Generator that turns the registry contents into the finished OpenAPI document, with its own generation options.
  • Emits OpenAPI 3 output, including reusable schemas referenced through $ref such as #/components/schemas/User.
  • Documents which Zod schema types are supported and which are unsupported.
  • Supports adding generation as part of a build step, and keeps a changelog in the GitHub releases.

Who uses it and how

  • Teams that validate API input with Zod and want a single source of truth instead of a parallel OpenAPI file, which is the maintainers' own stated reason for building it.
  • Node and TypeScript API projects that generate their specification at build time rather than serving it from a separate manually edited document.
  • Consumers running Zod v3, who must pin the package to 7.3.4; the maintainers state that this version is not intended to be actively supported going forward.
  • Anyone who already relies on the request.params and response schema objects for runtime validation and wants the same definitions reflected in the published documentation.

Getting started

Install with npm install @asteasolutions/zod-to-openapi or yarn add @asteasolutions/zod-to-openapi, then call extendZodWithOpenApi once in a common entry point before registering paths.

How it compares

The facts provided list no paid products that this project replaces, and they name no directly comparable tools. On the evidence available, it stands alone in this registry.

When to use it — and when not to

This is a library rather than a hosted service, so adopting it does not mean operating a database, object storage or an SMTP server; the work is limited to installing the package, wiring extendZodWithOpenApi into a shared entry point, and deciding where generation runs in the build. Teams that do not use Zod, or that prefer to author OpenAPI documents by hand, will get little from it, and anyone committed to Zod v3 should weigh the fact that support for that version is frozen at 7.3.4 and is not planned to be actively maintained. The repository also carries 39 open issues, which is worth reviewing before depending on it in a large surface area.

project readme (upstream, from github) — read inline

Zod to OpenAPI

npm version npm downloads

[!IMPORTANT] For Zod v3 support, please use the v7.3.4 version. However keep in mind that we do not intend to actively support that version going forward Install with: npm install @asteasolutions/[email protected]

A library that uses zod schemas to generate an Open API Swagger documentation.

  1. Purpose and quick example
  2. Usage
    1. Installation
    2. The openapi method
    3. The Registry
    4. The Generator
    5. Defining schemas
    6. Defining routes & webhooks
    7. Defining custom components
    8. A full example
    9. Adding it as part of your build
    10. Using schemas vs a registry
    11. Generation options
  3. Zod schema types
    1. Supported types
    2. Unsupported types
  4. Technologies

We keep a changelog as part of the GitHub releases.

Purpose and quick example

We at Astea Solutions made this library because we use zod for validation in our APIs and are tired of the duplication to also support a separate OpenAPI definition that must be kept in sync. Using zod-to-openapi, we generate OpenAPI definitions directly from our zod schemas, thus having a single source of truth.

Simply put, it turns this:

const UserSchema = z
  .object({
    id: z.string().openapi({ example: '1212121' }),
    name: z.string().openapi({ example: 'John Doe' }),
    age: z.number().openapi({ example: 42 }),
  })
  .openapi('User');

registry.registerPath({
  method: 'get',
  path: '/users/{id}',
  summary: 'Get a single user',
  request: {
    params: z.object({ id: z.string() }),
  },

  responses: {
    200: {
      description: 'Object with user data.',
      content: {
        'application/json': {
          schema: UserSchema,
        },
      },
    },
  },
});

into this:

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: '1212121'
        name:
          type: string
          example: John Doe
        age:
          type: number
          example: 42
      required:
        - id
        - name
        - age

/users/{id}:
  get:
    summary: Get a single user
    parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
    responses:
      '200':
        description: Object with user data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'

and you can still use UserSchema and the request.params object to validate the input of your API.

Usage

Installation

npm install @asteasolutions/zod-to-openapi
# or
yarn add @asteasolutions/zod-to-openapi

The openapi method

To keep openapi definitions natural, we add an openapi method to all Zod objects. Its idea is to provide a convenient way to provide OpenApi specific data. It has three overloads:

  1. .openapi({ [key]: value }) - this way we can specify any OpenApi fields. For example z.number().openapi({ example: 3 }) would add example: 3 to the generated schema.
  2. .openapi("") - this way we specify that the underlying zod schema should be "registered" i.e added into components/schemas with the provided ``
  3. .openapi("", { [key]: value }) - this unites the two use cases above so that we can specify both a registration `` and additional metadata

For this to work, you need to call extendZodWithOpenApi once in your project.

This should be done only once in a common-entrypoint file of your project (for example an index.ts/app.ts). If you're using tree-shaking with Webpack, mark that file as having side-effects.

It can be bit tricky to achieve this in your codebase, because require is synchronous and import is a async.

Using zod's .meta

Starting from v8 (and zod v4) you can also use zod's .meta to provide metadata and we will read it accordingly.

With zod's new option for generating JSON schemas and maintaining registries we've added a pretty much seamless support for all metadata information coming from .meta calls as if that was metadata passed into .openapi.

So the following 2 schemas produce exactly the same results:

const schema = z
  .string()
  .openapi('Schema', { description: 'Name of the user', example: 'Test' });

const schema2 = z
  .string()
  .meta({ id: 'Schema2', description: 'Name of the user', example: 'Test' });

Note: This also means that you unless you are using some of our more complicated scenarios you could even generate a schema without using extendZodWithOpenApi in your codebase and only rely on .meta to provide additional metadata information and schema names (using the id property).

Scenarios that require using extendZodWithOpenApi and .openapi
  1. When extending registered schemas that are both registered and want the extended one to use anyOf i.e:
const schema = z.object({ name: z.string() }).openapi('Schema');

const schema2 = schema.extend({ age: z.number() }).openapi('Schema2'); // this one would have anyOf and a reference to the first one
  1. Defining parameter metadata. So for example when doing:
registry.registerPath({
  // ...
  request: {
    query: z.object({
      name: z.string().openapi({
        description: 'Schema level description',
        param: { description: 'Param level description' },
      }),
    }),
  },
});

the result would be:

  "parameters": [
      {
        "schema": {
          "type": "string",
          "description": "Schema level description" // comes directly from description
        },
        "required": true,
        "description": "Param level description", // comes from param.description
        "name": "name",
        "in": "query"
      }
  ],

The basic idea

import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
import { z } from 'zod';

extendZodWithOpenApi(z);

// We can now use `.openapi()` to specify OpenAPI metadata
z.string().openapi({ description: 'Some string' });

Example 1: Calling the openapi-extension using tsx

//zod-extend.ts

import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
import { z } from 'zod';

extendZodWithOpenApi(z);

// package.json

  "scripts": {
    "start": "tsx --import ./zod-extend.ts ./index.ts",

Example 2 - require-syntax

import { extendZodWithOpenApi } from '@asteasolutions/zod-to-openapi';
import { z } from 'zod';

extendZodWithOpenApi(z);

const { startServer } = require('./server/start');
startServer();

The Registry

The OpenAPIRegistry is a utility that can be used to collect definitions which would later be passed to a OpenApiGeneratorV3 or OpenApiGeneratorV31 instance.

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

const registry = new OpenAPIRegistry();

// Register definitions here

const generator = new OpenApiGeneratorV3(registry.definitions);

return generator.generateComponents();

The Generator

There are three generators that can be used - OpenApiGeneratorV3, OpenApiGeneratorV31 and OpenApiGeneratorV32. They share the same interface but internally generate schemas that correctly follow the data format for the specific Open API version - 3.0.x, 3.1.x or 3.2.x. The Open API version affects how some components are generated.

OpenApiGeneratorV32 uses the same JSON Schema dialect as 3.1 (2020-12), so schemas are generated identically. It additionally accepts the document-structure fields that were added in 3.2 - see OpenAPI 3.2 support.

For example: changing the generator from OpenApiGeneratorV3 to OpenApiGeneratorV31 would result in following differences:

z.string().nullable().openapi({refId: 'name'});

# 3.1.0
# nullable is invalid in 3.1.0 but type arrays are invalid in previous versions
name:
  type:
    - 'string'
    - 'null'

# 3.0.0
name:
  type: 'string'
  nullable: true

Both generators take a single argument in their constructors - an array of definitions - i.e results from the registry or regular zod schemas.

Th

readme truncated — read the full docs on github

Frequently asked questions

Is zod-to-openapi free to use?

zod-to-openapi is open source under the MIT licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does zod-to-openapi do?

A library that generates OpenAPI (Swagger) docs from Zod schemas

What is zod-to-openapi written in?

zod-to-openapi is primarily written in TypeScript. Its source is publicly available at https://github.com/asteasolutions/zod-to-openapi, and it has 1,619 GitHub stars.