@origins-digital/zod-openapi-utils

A utility package that bridges Zod schemas with OpenAPI/Swagger documentation in NestJS applications.

Installation

``bash
npm install @origins-digital/zod-openapi-utils
`

Features

- Automatic conversion of Zod schemas to OpenAPI/Swagger schemas
- Support for all Zod types and validations including lazy schemas
- Type-safe API documentation
- Seamless integration with NestJS Swagger
- Custom format support (email, URL, UUID, CUID, etc.)
- Support for recursive and circular references

Usage

$3

`typescript
import { Module } from '@nestjs/common';
import { makeOpenAPIComponents } from '@origins-digital/zod-openapi-utils';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

@Module({})
export class AppModule {
constructor() {
const config = new DocumentBuilder()
.setTitle('Your API')
.setDescription('API description')
.setVersion('1.0')
.build();

const document = SwaggerModule.createDocument(app, config, {
extraModels: makeOpenAPIComponents([
// Your Zod schemas here
]),
});

SwaggerModule.setup('api', app, document);
}
}
`

$3

`typescript
import { z } from 'zod';
import { createZodDto } from '@origins-digital/zod-openapi-utils';

// Define your Zod schema with .openapi() decorator
const UserSchema = z
.object({
id: z.string().uuid(),
email: z.string().email(),
name: z.string().min(2).max(100),
age: z.number().int().min(0).max(120),
createdAt: z.date(),
password: z.string().min(8).password(),
})
.openapi({
title: 'User',
description: 'User entity schema',
});

// Create DTO from Zod schema
export class CreateUserDto extends createZodDto(UserSchema) {}

// Use it in your controller
@Controller('users')
export class UsersController {
@Post()
create(@Body() createUserDto: CreateUserDto) {
// The DTO will be validated against the Zod schema
return this.usersService.create(createUserDto);
}
}
``

$3

- Strings: email, URL, UUID, CUID, regex patterns, min/max length
- Numbers: integers, min/max values, multipleOf
- Dates: date-time format
- Booleans
- Objects: nested schemas
- Arrays: min/max length
- Unions and Enums
- Lazy Schemas: recursive and circular references
- Custom Formats: password, time, etc.
- Nested types: This package is also able to detect nested types when using the .openapi() method, and create the reference in the openapi spec.

Error Handling

The package includes a custom exception handler for Zod validation errors that integrates with NestJS's exception handling system.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.