nestjs-swagger-validator

One decorator to rule them all. Combines Swagger documentation and class-validator validation into a single @ApiProperty() call for your NestJS DTOs.

The Problem

A typical NestJS DTO looks like this:

import { ApiProperty } from '@nestjs/swagger';
import { IsDefined, IsString, IsEmail, MaxLength } from 'class-validator';

class CreateUserDto {
  @ApiProperty({ type: 'string', example: '[email protected]' })
  @IsDefined()
  @IsString()
  @IsEmail()
  @MaxLength(255)
  email: string;
}

5 decorators for a single field. It gets worse with optional/nullable fields.

The Solution

import { ApiProperty } from 'nestjs-swagger-validator';

class CreateUserDto {
  @ApiProperty({ type: 'string', example: '[email protected]', isEmail: true, maxLength: 255 })
  email: string;
}

1 decorator. Same Swagger docs. Same validation. Fully type-safe.

Installation

npm install nestjs-swagger-validator

Peer dependencies

npm install @nestjs/common @nestjs/swagger class-transformer class-validator

Usage

String

@ApiProperty({ type: 'string', example: 'hello' })
name: string;

@ApiProperty({ type: 'string', isEmail: true, example: '[email protected]' })
email: string;

@ApiProperty({ type: 'string', isUrl: true })
website: string;

@ApiProperty({ type: 'string', isPhone: true })
phone: string;

@ApiProperty({ type: 'string', isDate: true, example: '2024-01-01' })
birthDate: string;

@ApiProperty({ type: 'string', minLength: 8, maxLength: 128 })
password: string;

Number

@ApiProperty({ type: 'number', example: 25 })
age: number;

@ApiProperty({ type: 'number', isPositive: true })
price: number;

@ApiProperty({ type: 'number', isInt: true })
quantity: number;

Boolean

@ApiProperty({ type: 'boolean', example: true })
isActive: boolean;

Enum

enum Role { ADMIN = 'admin', USER = 'user' }

@ApiProperty({ enum: Role, example: Role.USER })
role: Role;

Nested objects

@ApiProperty({ type: AddressDto, typeClass: AddressDto, validateNested: true })
address: AddressDto;

Arrays

@ApiProperty({ type: 'string', isArray: true, arrayMinSize: 1 })
tags: string[];

@ApiProperty({ type: [ItemDto], isArray: true, typeClass: ItemDto, validateNested: true })
items: ItemDto[];

Optionality & Nullability

The decorator handles four cases based on required and nullable:

| Configuration | Accepts | Decorator behavior | |---|---|---| | (default) | value | @IsDefined() — must be present and non-null | | required: false | value \| undefined | @IsOptional() — can be omitted, but cannot be null | | nullable: true | value \| null | @IsNullable() — must be present, but can be null | | required: false, nullable: true | value \| null \| undefined | @IsOptional() — can be omitted or null |

@ApiProperty({ type: 'string', required: false })
bio?: string;

@ApiProperty({ type: 'string', nullable: true })
middleName: string | null;

@ApiProperty({ type: 'string', required: false, nullable: true })
nickname?: string | null;

Custom Validators

The package also exports IsNullable and IsUndefined validators for standalone use:

import { IsNullable, IsUndefined } from 'nestjs-swagger-validator';

License

MIT