Kurs NestJS · Moduł 11: Swagger i OpenAPI

Dokumentacja DTO - pieczęcie na pergaminie

3 min czytania ·
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:

OpcjaOpisPrzykład
descriptionOpis pola'Imię legionisty'
examplePrzykładowa wartość'Marcus'
requiredCzy pole jest wymaganetrue / false
defaultWartość domyślna'Miles'
enumLista dozwolonych wartości['Centurio', 'Miles']
typeTyp polaString, Number, Boolean
isArrayCzy pole jest tablicątrue
minimumMinimalna wartość (number)0
maximumMaksymalna wartość (number)100
minLengthMinimalna długość (string)2
maxLengthMaksymalna 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. 1. Co robi dekorator @ApiProperty() na polu klasy DTO?

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

  1. PytanieDekorator @ApiProperty
  2. PytaniePola opcjonalne w DTO
  3. Zadanie z kodemDekorowanie DTO @ApiProperty
  4. Ułóż w kolejnościDekorator @ApiProperty z enum
  5. Kliknij w kolejnościOpcje @ApiProperty
  6. Zadanie z kodemDTO z enum i zagnieżdżonym typem
  7. PytanieZagnieżdżone DTO w Swagger

Przydatne artykuły