# @anatine/zod-openapi > Zod to OpenAPI converter Latest version **2.2.8** (published 2025-04-04) · MIT license · 0 weekly downloads ## Install ```sh npm install @anatine/zod-openapi pnpm add @anatine/zod-openapi yarn add @anatine/zod-openapi bun add @anatine/zod-openapi ``` ## Health **Score 40/100 (D)** — status: stable. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: stale. ## Facts | | | |---|---| | Version | 2.2.8 | | Published | 2025-04-04 | | First published | 2021-07-11 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 1 | | Unpacked size | 48.7 KB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | GitHub stars | 768 | | Author | Brian McBride | | Maintainers | anatidae | | Keywords | zod, openapi, swagger | ## Links - npm: https://www.npmjs.com/package/@anatine/zod-openapi - Repository: https://github.com/anatine/zod-plugins - Homepage: https://github.com/anatine/zod-plugins/tree/main/packages/zod-openapi - Issues: https://github.com/anatine/zod-plugins/issues - npm.io page: https://npm.io/package/@anatine/zod-openapi ## Dependencies (1) - [ts-deepmerge](https://npm.io/package/ts-deepmerge.md) ^6.0.3 ## Alternatives - [vest](https://npm.io/package/vest.md) — 50.1K weekly downloads - [@regle/core](https://npm.io/package/@regle/core.md) — 47.0K weekly downloads - [typeof-arguments](https://npm.io/package/typeof-arguments.md) — 12.5K weekly downloads - [@lokalise/projects-engine-contracts](https://npm.io/package/@lokalise/projects-engine-contracts.md) — 978 weekly downloads - [@osjwnpm/nam-laboriosam-quibusdam](https://npm.io/package/@osjwnpm/nam-laboriosam-quibusdam.md) — 70 weekly downloads ## Recent versions - 2.2.8 (latest) — 2025-04-04 - 2.2.7 — 2025-01-20 - 2.2.6 — 2024-06-21 - 2.2.5 — 2024-03-20 - 2.2.4 — 2024-03-19 - 2.2.3 — 2024-01-23 - 2.2.2 — 2023-12-15 - 2.2.1 — 2023-10-31 - 2.2.0 — 2023-08-22 - 2.1.0 — 2023-08-03 - 2.0.1 — 2023-06-30 - 2.0.0 — 2023-06-30 - 1.14.2 — 2023-06-16 - 1.14.1 — 2023-06-16 - 1.14.0 — 2023-05-23 - … 32 more at https://npm.io/package/@anatine/zod-openapi/versions ## README # @anatine/zod-openapi Converts a [Zod](https://github.com/colinhacks/zod) schema to an OpenAPI `SchemaObject` as defined by [openapi3-ts](https://www.npmjs.com/package/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. ```shell npm install openapi3-ts zod @anatine/zod-openapi ``` ---- ## Usage ### Take any Zod schema and convert it to an OpenAPI JSON object ```typescript 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` ```json { "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 ```typescript 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: ```typescript 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: ```json { "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](https://github.com/RobinTail/express-zod-api) A great lib that provided some insights on dealing with various zod types. - ### [zod-dto](https://github.com/kbkk/abitia/tree/master/packages/zod-dto) Lib providing insights into using Zod with NestJS ---- This library is part of a nx monorepo [@anatine/zod-plugins](https://github.com/anatine/zod-plugins). --- _Source: https://npm.io/package/@anatine/zod-openapi · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._