@st-api/zod-openapi

Fork of @anatine/zod-openapi

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

This fork was made because of a breaking change in the @anatine/zod-openapi@2.2.4, which introduced a incompatibility with OpenAPI Specification v3.0. The original library is no longer compatible with OAS30, it's only compatible with OAS31.

---

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.

1pnpm add openapi3-ts zod @st-api/zod-openapi

---

Usage

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

1import { generateSchema } from '@st-api/zod-openapi';
2const aZodSchema = z.object({
3  uid: z.string().nonempty(),
4  firstName: z.string().min(2),
5  lastName: z.string().optional(),
6  email: z.string().email(),
7  phoneNumber: z.string().min(10).optional(),
8})
9const myOpenApiSchema = generateSchema(aZodSchema);
10// ...

This will generate an OpenAPI schema for myOpenApiSchema

1{
2  "type": "object",
3  "properties": {
4    "uid": {
5      "type": "string",
6      "minLength": 1
7    },
8    "firstName": {
9      "type": "string",
10      "minLength": 2
11    },
12    "lastName": {
13      "type": "string"
14    },
15    "email": {
16      "type": "string",
17      "format": "email"
18    },
19    "phoneNumber": {
20      "type": "string",
21      "minLength": 10
22    }
23  },
24  "required": [
25    "uid",
26    "firstName",
27    "email"
28  ]
29}

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

1import { extendApi, generateSchema } from '@st-api/zod-openapi';
2const aZodExtendedSchema = extendApi(
3      z.object({
4        uid: extendApi(z.string().nonempty(), {
5          title: 'Unique ID',
6          description: 'A UUID generated by the server',
7        }),
8        firstName: z.string().min(2),
9        lastName: z.string().optional(),
10        email: z.string().email(),
11        phoneNumber: extendApi(z.string().min(10), {
12          description: 'US Phone numbers only',
13          example: '555-555-5555',
14        }),
15      }),
16      {
17        title: 'User',
18        description: 'A user schema',
19      }
20    );
21const myOpenApiSchema = generateSchema(aZodExtendedSchema);
22// ...

... or via extension of the Zod schema:

1import { extendApi, generateSchema, extendZodWithOpenApi } from '@anatine/zod-openapi';
2import {z} from 'zod';
3
4extendZodWithOpenApi(z);
5
6const aZodExtendedSchema = 
7      z.object({
8        uid: z.string().nonempty().openapi({
9          title: 'Unique ID',
10          description: 'A UUID generated by the server',
11        }),
12        firstName: z.string().min(2),
13        lastName: z.string().optional(),
14        email: z.string().email(),
15        phoneNumber: z.string().min(10).openapi({
16          description: 'US Phone numbers only',
17          example: '555-555-5555',
18        }),
19      }).openapi(
20      {
21        title: 'User',
22        description: 'A user schema',
23      }
24    );
25const myOpenApiSchema = generateSchema(aZodExtendedSchema);
26// ...

This will generate an extended schema:

1{
2  "type": "object",
3  "properties": {
4    "uid": {
5      "type": "string",
6      "minLength": 1,
7      "title": "Unique ID",
8      "description": "A UUID generated by the server"
9    },
10    "firstName": {
11      "type": "string",
12      "minLength": 2
13    },
14    "lastName": {
15      "type": "string"
16    },
17    "email": {
18      "type": "string",
19      "format": "email"
20    },
21    "phoneNumber": {
22      "type": "string",
23      "minLength": 10,
24      "description": "US Phone numbers only",
25      "example": "555-555-5555"
26    }
27  },
28  "required": [
29    "uid",
30    "firstName",
31    "email",
32    "phoneNumber"
33  ],
34  "title": "User",
35  "description": "A user schema"
36}

---

Credits

• @anatine/zod-openapi

  The original library that was forked.