NestJS course ยท Module 11: Swagger and OpenAPI
DTO Documentation - Seals on Parchment
In this lesson7
Every document in the imperial chancellery had to have precisely described fields - the petitioner's name, the type of matter, the date, and the seal. In NestJS, the equivalent of these documents are DTOs (Data Transfer Objects), and the @ApiProperty() decorator describes each field so that Swagger UI can display it.
@ApiProperty - Basics
The @ApiProperty() decorator describes a single field in a DTO class:
import { ApiProperty } from '@nestjs/swagger';
export class CreateLegionaryDto {
@ApiProperty({
description: 'Name of the legionary',
example: 'Marcus Aurelius',
})
name: string;
@ApiProperty({
description: 'Rank in the legion',
example: 'Centurio',
})
rank: string;
@ApiProperty({
description: 'Years of experience',
example: 5,
minimum: 0,
maximum: 40,
})
experience: number;
}@ApiProperty Options
The decorator accepts many configuration options:
| Option | Description | Example |
|---|---|---|
description | Field description | 'Name of the legionary' |
example | Example value | 'Marcus' |
required | Whether the field is required | true / false |
default | Default value | 'Miles' |
enum | List of allowed values | ['Centurio', 'Miles'] |
type | Field type | String, Number, Boolean |
isArray | Whether the field is an array | true |
minimum | Minimum value (number) | 0 |
maximum | Maximum value (number) | 100 |
minLength | Minimum length (string) | 2 |
maxLength | Maximum length (string) | 50 |
Optional Fields with @ApiPropertyOptional
For optional fields, we use @ApiPropertyOptional():
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
export class UpdateLegionaryDto {
@ApiPropertyOptional({
description: 'New rank of the legionary',
example: 'Optio',
})
rank?: string;
@ApiPropertyOptional({
description: 'New assigned legion',
example: 'Legio III Augusta',
})
legio?: string;
@ApiPropertyOptional({
description: 'Additional experience',
example: 2,
minimum: 0,
})
additionalExperience?: number;
}Fields with enum - Legion Ranks
Enum is particularly useful for fields with a limited set of values:
export enum LegionaryRank {
MILES = 'Miles',
OPTIO = 'Optio',
CENTURIO = 'Centurio',
TRIBUNUS = 'Tribunus',
LEGATUS = 'Legatus',
}
export class CreateLegionaryDto {
@ApiProperty({
description: 'Rank of the legionary',
enum: LegionaryRank,
example: LegionaryRank.MILES,
})
rank: LegionaryRank;
}Nested Objects - Legion Structure
For nested DTOs, we use the type option:
export class AddressDto {
@ApiProperty({ description: 'Province name', example: 'Pannonia' })
province: string;
@ApiProperty({ description: 'City name', example: 'Aquincum' })
city: string;
}
export class LegionDto {
@ApiProperty({ description: 'Legion name', example: 'Legio X Gemina' })
name: string;
@ApiProperty({
description: 'Legion location',
type: AddressDto,
})
location: AddressDto;
@ApiProperty({
description: 'List of centurions',
type: [String],
example: ['Marcus', 'Julius', 'Gaius'],
})
centurions: string[];
}Response DTOs
It is a good practice to create separate DTOs for API responses:
export class LegionaryResponseDto {
@ApiProperty({ description: 'Legionary ID', example: '507f1f77bcf86cd799439011' })
id: string;
@ApiProperty({ description: 'Name of the legionary', example: 'Marcus Aurelius' })
name: string;
@ApiProperty({ description: 'Rank', enum: LegionaryRank })
rank: LegionaryRank;
@ApiProperty({ description: 'Recruitment date', example: '2024-01-15T10:30:00Z' })
recruitedAt: Date;
@ApiProperty({ description: 'Is active', example: true })
isActive: boolean;
}Practical Exercise
Create DTO documentation for the Empire's province management system:
Code for this lesson: src/province.dto.ts
// DTO documentation - seals on parchment
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
// TODO: Create enum ProvinceStatus with values:
// ACTIVE = 'Active', CONQUERED = 'Conquered', REBELLING = 'Rebelling'
export enum ProvinceStatus {
// TODO: Complete the enum values
}
export class CreateProvinceDto {
// TODO: Add @ApiProperty with description and example
name: string;
// TODO: Add @ApiProperty with description and example
governor: string;
// TODO: Add @ApiProperty with enum ProvinceStatus
status: ProvinceStatus;
// TODO: Add @ApiPropertyOptional with description, example, minimum
population?: number;
// TODO: Add @ApiProperty with description and type [String]
legions: string[];
}
export class ProvinceResponseDto {
@ApiProperty({ description: 'Province ID', example: '64a1b2c3d4e5f6a7b8c9d0e1' })
id: string;
@ApiProperty({ description: 'Province name', example: 'Pannonia' })
name: string;
@ApiProperty({ description: 'Governor', example: 'Lucius Verus' })
governor: string;
@ApiProperty({ description: 'Province status', enum: ProvinceStatus })
status: ProvinceStatus;
@ApiPropertyOptional({ description: 'Population', example: 500000 })
population?: number;
@ApiProperty({ description: 'Annexation date' })
annexedAt: Date;
}
console.log("@ApiProperty - required fields");
console.log("@ApiPropertyOptional - optional fields");
console.log("Options: description, example, enum, type");
console.log("minimum, maximum, minLength, maxLength");
Docs entries used in this lesson
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What does the @ApiProperty() decorator do on a DTO class field?
2. Which decorator is used to mark optional fields in a DTO for Swagger?
These are 2 of 3 questions for this lesson. Solve the rest in the game.
Hands-on tasks in the game
- Code editor
Complete CreateCenturioDto by adding @ApiProperty with description and example to each field
- Vertical ordering
Arrange the elements of @ApiProperty with enum in the correct order:
- Click in order
Arrange the @ApiProperty options from description to value validation:
- Code editor
Complete CreateProvinceDto with enum ProvinceType, nested LocationDto, and a string array