NestJS course ยท Module 11: Swagger and OpenAPI

DTO Documentation - Seals on Parchment

3 min read ยท
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:

OptionDescriptionExample
descriptionField description'Name of the legionary'
exampleExample value'Marcus'
requiredWhether the field is requiredtrue / false
defaultDefault value'Miles'
enumList of allowed values['Centurio', 'Miles']
typeField typeString, Number, Boolean
isArrayWhether the field is an arraytrue
minimumMinimum value (number)0
maximumMaximum value (number)100
minLengthMinimum length (string)2
maxLengthMaximum 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. 1. What does the @ApiProperty() decorator do on a DTO class field?

  2. 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

  1. QuestionThe @ApiProperty Decorator
  2. QuestionOptional Fields in DTO
  3. Coding taskDecorating a DTO with @ApiProperty
  4. Put in order@ApiProperty Decorator with enum
  5. Click in order@ApiProperty Options
  6. Coding taskDTO with enum and Nested Type
  7. QuestionNested DTO in Swagger

Useful articles