Zod to OpenAPI
A library that uses zod schemas to generate an Open API Swagger documentation.
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, this having single source of truth.
Simply put, it turns this:
const UserSchema = registry.register(
'User',
z.object({
id: z.string().openapi({ example: '1212121' }),
name: z.string().openapi({ example: 'John Doe' }),
age: z.number().openapi({ example: 42 }),
})
);
registry.registerPath({
method: 'get',
path: '/users/{id}',
summary: 'Get a single user',
request: {
params: z.object({ id: z.string() }),
},
responses: {
200: {
mediaType: 'application/json',
schema: UserSchema.openapi({
description: 'Object with user data',
}),
}
},
});
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
openapi
method
The To keep openapi definitions natural, we add an openapi
method to all Zod objects. For this to work, you need to call extendZodWithOpenApi
once in your project.
Note: 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.
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' });
The Registry
The OpenAPIRegistry
is used to track definitions which are later generated using the OpenAPIGenerator
class.
import {
OpenAPIRegistry,
OpenAPIGenerator,
} from '@asteasolutions/zod-to-openapi';
const registry = new OpenAPIRegistry();
// Register definitions here
const generator = new OpenAPIGenerator(registry.definitions);
return generator.generateComponents();
generateComponents
will generate only the /components
section of an OpenAPI document (e.g. only schemas
and parameters
), not generating actual routes.
Defining schemas
An OpenAPI schema should be registered using the register
method of an OpenAPIRegistry
instance.
const UserSchema = registry.register(
'User',
z.object({
id: z.string().openapi({ example: '1212121' }),
name: z.string().openapi({ example: 'John Doe' }),
age: z.number().openapi({ example: 42 }),
})
);
If run now, generateComponents
will generate the following structure:
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
The key for the schema in the output is the first argument passed to .register
(in this case - User
).
Note that generateComponents
does not return YAML but a JS object - you can then serialize that object into YAML or JSON depending on your use-case.
The resulting schema can then be referenced by using $ref: #/components/schemas/User
in an existing OpenAPI JSON. This will be done automatically for Routes defined through the registry.
Defining routes
Registering a path
An OpenAPI path is registered using the registerPath
method of an OpenAPIRegistry
instance.
registry.registerPath({
method: 'get',
path: '/users/{id}',
description: 'Get user data by its id',
summary: 'Get a single user',
request: {
params: z.object({
id: z.string().openapi({ example: '1212121' })
}),
},
responses: {
200: {
mediaType: 'application/json',
schema: UserSchema.openapi({
description: 'Object with user data.',
}),
},
204: z.void(),
},
});
The YAML equivalent of the schema above would be:
'/users/{id}':
get:
description: Get user data by its id
summary: Get a single user
parameters:
- in: path
name: id
schema:
type: string
example: '1212121'
required: true
responses:
'200':
description: Object with user data.
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'204':
description: No content - successful operation
The library specific properties for registerPath
are method
, path
, request
and responses
. Everything else gets directly appended to the path definition.
method
- One ofget
,post
,put
,delete
andpatch
;path
- a string - being the path of the endpoint;request
- an optional object with optionalbody
,params
,query
andheaders
keys,query
,params
- being instances ofZodObject
body
- being anyzod
instanceheaders
- an array ofzod
instances
responses
- an object where the key is the status code ordefault
and the value is either:- an instance of
ZodVoid
- meaning a no content response - an object with
mediaType
(a string likeapplication/json
) and aschema
of any zod type
- an instance of
Defining route parameters
If you don't want to inline all parameter definitions, you can define them separately with registerParameter
and then reference them:
const UserIdParam = registry.registerParameter(
'UserId',
z.string().openapi({
param: {
name: 'id',
in: 'path',
},
example: '1212121',
})
);
registry.registerPath({
...
request: {
params: z.object({
id: UserIdParam
}),
},
responses: ...
});
The YAML equivalent would be:
components:
parameters:
UserId:
in: path
name: id
schema:
type: string
example: '1212121'
required: true
'/users/{id}':
get:
...
parameters:
- $ref: '#/components/parameters/UserId'
responses: ...
Note: In order to define properties that apply to the parameter itself, use the param
property of .openapi
. Any properties provided outside of param
would be applied to the schema for this parameter.
Generating the full document
A full OpenAPI document can be generated using the generateDocument
method of an OpenAPIGenerator
instance. It takes one argument - the document config. It may look something like this:
return generator.generateDocument({
openapi: '3.0.0',
info: {
version: '1.0.0',
title: 'My API',
description: 'This is the API',
},
servers: [{ url: 'v1' }],
});
A full example
A full example code can be found here. And the YAML representation of its result - here
Adding it as part of your build
In a file inside your project you can have a file like so:
export const registry = new OpenAPIRegistry();
export function generateOpenAPI() {
const config = {...}; // your config comes here
return new OpenAPIGenerator(schemas.definitions).generateDocument(config);
}
You then use the exported registry
object to register all schemas, parameters and routes where appropriate.
Then you can create a script that executes the exported generateOpenAPI
function. This script can be executed as a part of your build step so that it can write the result to some file like openapi-docs.json
.