@esmkit/zod-openapi
v0.1.0
Published
Converts a zod schema to an OpenAPI
Downloads
4
Readme
@esmkit/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 @esmkit/zod-openapi
Usage
Take any Zod schema and convert it to an OpenAPI JSON object
import { generateSchema } from "@esmkit/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 "@esmkit/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 "@esmkit/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"
}
This library is part of a nx monorepo @esmkit/zod-plugins.