@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

The README file is missing