Kurs NestJS · Moduł 11: Swagger i OpenAPI
Dokumentacja DTO - pieczęcie na pergaminie
W tej lekcji7
Każdy dokument w cesarskiej kancelarii musiał mieć precyzyjnie opisane pola - imię petenta, rodzaj sprawy, datę i pieczęć. W NestJS odpowiednikiem tych dokumentów są DTO (Data Transfer Objects), a dekorator @ApiProperty() opisuje każde pole tak, aby Swagger UI mógł je wyświetlić.
@ApiProperty - Podstawy
Dekorator @ApiProperty() opisuje pojedyncze pole w klasie DTO:
import { ApiProperty } from '@nestjs/swagger';
export class CreateLegionaryDto {
@ApiProperty({
description: 'Imię legionisty',
example: 'Marcus Aurelius',
})
name: string;
@ApiProperty({
description: 'Ranga w legionie',
example: 'Centurio',
})
rank: string;
@ApiProperty({
description: 'Lata doświadczenia',
example: 5,
minimum: 0,
maximum: 40,
})
experience: number;
}Opcje @ApiProperty
Dekorator przyjmuje wiele opcji konfiguracyjnych:
| Opcja | Opis | Przykład |
|---|---|---|
description | Opis pola | 'Imię legionisty' |
example | Przykładowa wartość | 'Marcus' |
required | Czy pole jest wymagane | true / false |
default | Wartość domyślna | 'Miles' |
enum | Lista dozwolonych wartości | ['Centurio', 'Miles'] |
type | Typ pola | String, Number, Boolean |
isArray | Czy pole jest tablicą | true |
minimum | Minimalna wartość (number) | 0 |
maximum | Maksymalna wartość (number) | 100 |
minLength | Minimalna długość (string) | 2 |
maxLength | Maksymalna długość (string) | 50 |
Pola opcjonalne z @ApiPropertyOptional
Dla pól opcjonalnych używamy @ApiPropertyOptional():
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
export class UpdateLegionaryDto {
@ApiPropertyOptional({
description: 'Nowa ranga legionisty',
example: 'Optio',
})
rank?: string;
@ApiPropertyOptional({
description: 'Nowy legion przypisania',
example: 'Legio III Augusta',
})
legio?: string;
@ApiPropertyOptional({
description: 'Dodatkowe doświadczenie',
example: 2,
minimum: 0,
})
additionalExperience?: number;
}Pola z enum - rangi legionowe
Enum jest szczególnie przydatny do pól z ograniczonym zestawem wartości:
export enum LegionaryRank {
MILES = 'Miles',
OPTIO = 'Optio',
CENTURIO = 'Centurio',
TRIBUNUS = 'Tribunus',
LEGATUS = 'Legatus',
}
export class CreateLegionaryDto {
@ApiProperty({
description: 'Ranga legionisty',
enum: LegionaryRank,
example: LegionaryRank.MILES,
})
rank: LegionaryRank;
}Zagnieżdżone obiekty - struktura legionu
Dla zagnieżdżonych DTO używamy opcji type:
export class AddressDto {
@ApiProperty({ description: 'Nazwa prowincji', example: 'Pannonia' })
province: string;
@ApiProperty({ description: 'Nazwa miasta', example: 'Aquincum' })
city: string;
}
export class LegionDto {
@ApiProperty({ description: 'Nazwa legionu', example: 'Legio X Gemina' })
name: string;
@ApiProperty({
description: 'Lokalizacja legionu',
type: AddressDto,
})
location: AddressDto;
@ApiProperty({
description: 'Lista centurionów',
type: [String],
example: ['Marcus', 'Julius', 'Gaius'],
})
centurions: string[];
}DTO odpowiedzi
Warto tworzyć osobne DTO dla odpowiedzi API:
export class LegionaryResponseDto {
@ApiProperty({ description: 'ID legionisty', example: '507f1f77bcf86cd799439011' })
id: string;
@ApiProperty({ description: 'Imię legionisty', example: 'Marcus Aurelius' })
name: string;
@ApiProperty({ description: 'Ranga', enum: LegionaryRank })
rank: LegionaryRank;
@ApiProperty({ description: 'Data rekrutacji', example: '2024-01-15T10:30:00Z' })
recruitedAt: Date;
@ApiProperty({ description: 'Czy aktywny', example: true })
isActive: boolean;
}Ćwiczenie praktyczne
Stwórz dokumentację DTO dla systemu zarządzania prowincjami Imperium:
Kod do tej lekcji: src/province.dto.ts
// Dokumentacja DTO - pieczecie na pergaminie
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
// TODO: Stworz enum ProvinceStatus z wartosciami:
// ACTIVE = 'Active', CONQUERED = 'Conquered', REBELLING = 'Rebelling'
export enum ProvinceStatus {
// TODO: Uzupelnij wartosci enum
}
export class CreateProvinceDto {
// TODO: Dodaj @ApiProperty z description i example
name: string;
// TODO: Dodaj @ApiProperty z description i example
governor: string;
// TODO: Dodaj @ApiProperty z enum ProvinceStatus
status: ProvinceStatus;
// TODO: Dodaj @ApiPropertyOptional z description, example, minimum
population?: number;
// TODO: Dodaj @ApiProperty z description i type [String]
legions: string[];
}
export class ProvinceResponseDto {
@ApiProperty({ description: 'ID prowincji', example: '64a1b2c3d4e5f6a7b8c9d0e1' })
id: string;
@ApiProperty({ description: 'Nazwa prowincji', example: 'Pannonia' })
name: string;
@ApiProperty({ description: 'Namiestnik', example: 'Lucius Verus' })
governor: string;
@ApiProperty({ description: 'Status prowincji', enum: ProvinceStatus })
status: ProvinceStatus;
@ApiPropertyOptional({ description: 'Populacja', example: 500000 })
population?: number;
@ApiProperty({ description: 'Data aneksji' })
annexedAt: Date;
}
console.log("@ApiProperty - wymagane pola");
console.log("@ApiPropertyOptional - opcjonalne pola");
console.log("Opcje: description, example, enum, type");
console.log("minimum, maximum, minLength, maxLength");
Hasła z dokumentacji w tej lekcji
Widzisz błąd w tej lekcji?
Sprawdź się
Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.
1. Co robi dekorator @ApiProperty() na polu klasy DTO?
2. Jaki dekorator służy do oznaczania pól opcjonalnych w DTO dla Swagger?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Uzupełnij CreateCenturioDto dodając @ApiProperty z description i example do każdego pola
- Układanie w pionie
Ułóż elementy @ApiProperty z enum w prawidłowej kolejności:
- Klikanie w kolejności
Ułóż opcje @ApiProperty od opisu do walidacji wartości:
- Edytor kodu
Uzupełnij CreateProvinceDto z enum ProvinceType, zagnieżdżonym LocationDto i tablicą stringów