@anatine/zod-openapi

What is @anatine/zod-openapi?

@anatine/zod-openapi is an npm package that bridges the gap between Zod, a TypeScript-first schema declaration and validation library, and OpenAPI, a standard for defining RESTful APIs. This package allows developers to generate OpenAPI documentation from Zod schemas, making it easier to maintain API documentation in sync with the actual code.

What are @anatine/zod-openapi's main functionalities?

Generate OpenAPI Schema from Zod Schema

This feature allows you to generate an OpenAPI schema from a Zod schema. The code sample demonstrates how to define a Zod schema for a User object and then convert it into an OpenAPI schema.

const { z } = require('zod');
const { openApi } = require('@anatine/zod-openapi');

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email()
});

const openApiSchema = openApi({
  title: 'User API',
  version: '1.0.0',
  schemas: {
    User: UserSchema
  }
});

console.log(JSON.stringify(openApiSchema, null, 2));

Add Metadata to Zod Schemas

This feature allows you to add OpenAPI metadata directly to Zod schemas. The code sample shows how to extend Zod with OpenAPI capabilities and add descriptions to the fields in a User schema.

const { z } = require('zod');
const { extendZodWithOpenApi } = require('@anatine/zod-openapi');

extendZodWithOpenApi(z);

const UserSchema = z.object({
  id: z.string().openapi({ description: 'User ID' }),
  name: z.string().openapi({ description: 'User Name' }),
  email: z.string().email().openapi({ description: 'User Email' })
});

console.log(UserSchema.openapi);

Generate OpenAPI Documentation

This feature allows you to generate a full OpenAPI documentation from Zod schemas. The code sample demonstrates how to define a Zod schema, convert it to an OpenAPI schema, and then generate the full OpenAPI documentation.

const { z } = require('zod');
const { openApi, generateOpenApiDocument } = require('@anatine/zod-openapi');

const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email()
});

const openApiSchema = openApi({
  title: 'User API',
  version: '1.0.0',
  schemas: {
    User: UserSchema
  }
});

const openApiDocument = generateOpenApiDocument(openApiSchema);

console.log(JSON.stringify(openApiDocument, null, 2));

Other packages similar to @anatine/zod-openapi

zod-to-openapi

zod-to-openapi is another package that converts Zod schemas to OpenAPI documentation. It offers similar functionality to @anatine/zod-openapi but may have different API design and additional features. It is a good alternative if you are looking for different options in the same space.

ts-json-schema-generator

ts-json-schema-generator generates JSON schema from TypeScript types. While it does not directly generate OpenAPI documentation, JSON schema can be used as a base for OpenAPI schemas. This package is useful if you are working with TypeScript and need to generate schemas for validation or documentation purposes.

openapi-typescript

openapi-typescript generates TypeScript types from OpenAPI schemas. It works in the opposite direction compared to @anatine/zod-openapi, but it can be useful in a workflow where you start with OpenAPI documentation and want to generate TypeScript types for use in your application.

README

@anatine/zod-openapi

Converts a Zod schema to an OpenAPI SchemaObject as defined by openapi3-ts

---

Installation

Both openapi3-ts and zod are peer dependencies instead of dependant packages. While zod is necessary for operation, openapi3-ts is for type-casting.

npm install openapi3-ts zod @anatine/zod-openapi

---

Usage

Take any Zod schema and convert it to an OpenAPI JSON object

import { generateSchema } from '@anatine/zod-openapi';
const aZodSchema = z.object({
  uid: z.string().nonempty(),
  firstName: z.string().min(2),
  lastName: z.string().optional(),
  email: z.string().email(),
  phoneNumber: z.string().min(10).optional(),
})
const myOpenApiSchema = generateSchema(aZodSchema);
// ...

This will generate an OpenAPI schema for myOpenApiSchema

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "minLength": 1
    },
    "firstName": {
      "type": "string",
      "minLength": 2
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "phoneNumber": {
      "type": "string",
      "minLength": 10
    }
  },
  "required": [
    "uid",
    "firstName",
    "email"
  ]
}

Extend a Zod schema with additional OpenAPI schema via a function wrapper

import { extendApi, generateSchema } from '@anatine/zod-openapi';
const aZodExtendedSchema = extendApi(
      z.object({
        uid: extendApi(z.string().nonempty(), {
          title: 'Unique ID',
          description: 'A UUID generated by the server',
        }),
        firstName: z.string().min(2),
        lastName: z.string().optional(),
        email: z.string().email(),
        phoneNumber: extendApi(z.string().min(10), {
          description: 'US Phone numbers only',
          example: '555-555-5555',
        }),
      }),
      {
        title: 'User',
        description: 'A user schema',
      }
    );
const myOpenApiSchema = generateSchema(aZodExtendedSchema);
// ...

... or via extension of the Zod schema:

import { extendApi, generateSchema, extendZodWithOpenApi } from '@anatine/zod-openapi';
import {z} from 'zod';

extendZodWithOpenApi(z);

const aZodExtendedSchema = 
      z.object({
        uid: z.string().nonempty().openapi({
          title: 'Unique ID',
          description: 'A UUID generated by the server',
        }),
        firstName: z.string().min(2),
        lastName: z.string().optional(),
        email: z.string().email(),
        phoneNumber: z.string().min(10).openapi({
          description: 'US Phone numbers only',
          example: '555-555-5555',
        }),
      }).openapi(
      {
        title: 'User',
        description: 'A user schema',
      }
    );
const myOpenApiSchema = generateSchema(aZodExtendedSchema);
// ...

This will generate an extended schema:

{
  "type": "object",
  "properties": {
    "uid": {
      "type": "string",
      "minLength": 1,
      "title": "Unique ID",
      "description": "A UUID generated by the server"
    },
    "firstName": {
      "type": "string",
      "minLength": 2
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "phoneNumber": {
      "type": "string",
      "minLength": 10,
      "description": "US Phone numbers only",
      "example": "555-555-5555"
    }
  },
  "required": [
    "uid",
    "firstName",
    "email",
    "phoneNumber"
  ],
  "title": "User",
  "description": "A user schema"
}

---

Credits

• express-zod-api

  A great lib that provided some insights on dealing with various zod types.

• zod-dto

  Lib providing insights into using Zod with NestJS

---

This library is part of a nx monorepo @anatine/zod-plugins.