Nest Swagger

NestJS Swagger @ApiProperty Skill

When adding or modifying @ApiProperty() decorators in NestJS DTOs, follow these rules to ensure the generated Swagger schema accurately reflects the TypeScript types.

Rules

1. Optional fields (IsOptional)

If a property uses @IsOptional() or has ? in its TypeScript type, apply required: false:

@ApiProperty({ required: false })
@IsOptional()
name?: string;

2. Nullable fields

If a property's type includes null, apply nullable: true:

@ApiProperty({ nullable: true })
deletedAt: Date | null;

Combine with optional when both apply:

@ApiProperty({ required: false, nullable: true })
@IsOptional()
reason?: string | null;

3. Enum fields

Always provide both enum and enumName:

@ApiProperty({ enum: StatusEnum, enumName: 'StatusEnum' })
status: StatusEnum;

4. Array fields

Use type + isArray: true instead of wrapping in []:

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

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

5. Combining rules

Apply all applicable rules together:

// optional array of enums
@ApiProperty({ enum: RoleEnum, enumName: 'RoleEnum', isArray: true, required: false })
@IsOptional()
roles?: RoleEnum[];

// nullable enum
@ApiProperty({ enum: StatusEnum, enumName: 'StatusEnum', nullable: true })
status: StatusEnum | null;