Kurs NestJS · Moduł 11: Swagger i OpenAPI

CLI Plugin - automatyczny skryba

3 min czytania ·
W tej lekcji8

Wyobraź sobie, że w cesarskiej kancelarii masz skrybę, który automatycznie dokumentuje każdy dekret na podstawie jego treści - nie musisz mu mówić, co ma zapisać, sam rozumie strukturę dokumentu. Dokładnie tak działa CLI Plugin @nestjs/swagger.

Problem z ręczną dokumentacją

Bez CLI Plugin musisz ręcznie dodawać @ApiProperty() do każdego pola w każdym DTO:

// Bez CLI Plugin - dużo powtarzalnego kodu
export class CreateLegionaryDto {
  @ApiProperty({ description: 'Imię legionisty' })
  name: string;

  @ApiProperty({ description: 'Ranga', required: false })
  rank?: string;

  @ApiProperty({ description: 'Doświadczenie' })
  experience: number;

  @ApiProperty({ description: 'Czy aktywny' })
  isActive: boolean;
}

CLI Plugin - automatyczne generowanie

CLI Plugin analizuje typy TypeScript i automatycznie generuje metadane Swagger. Wystarczy prosta klasa:

// Z CLI Plugin - czysty kod, automatyczna dokumentacja
export class CreateLegionaryDto {
  /** Imię legionisty */
  name: string;

  /** Ranga w legionie */
  rank?: string;

  /** Lata doświadczenia */
  experience: number;

  /** Czy legionista jest aktywny */
  isActive: boolean;
}

Plugin automatycznie:

  • Rozpoznaje typy pól (string, number, boolean)
  • Oznacza pola z ? jako opcjonalne
  • Zamienia komentarze JSDoc na opisy w Swagger
  • Generuje odpowiednie @ApiProperty() w czasie kompilacji

Konfiguracja w nest-cli.json

Aby włączyć CLI Plugin, dodaj odpowiednią konfigurację w pliku nest-cli.json:

{
  "collection": "@nestjs/schematics",
  "sourceRoot": "src",
  "compilerOptions": {
    "deleteOutDir": true,
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": true,
          "introspectComments": true,
          "dtoFileNameSuffix": [".dto.ts", ".entity.ts"]
        }
      }
    ]
  }
}

Opcje CLI Plugin

OpcjaOpisDomyślna
classValidatorShimAutomatycznie dodaje reguły walidacji z class-validatortrue
introspectCommentsUżywa komentarzy JSDoc jako opisówfalse
dtoFileNameSuffixJakie pliki analizować['.dto.ts', '.entity.ts']
controllerFileNameSuffixSufiks plików kontrolerów'.controller.ts'
controllerKeyOfCommentKlucz komentarza dla kontrolerów'description'

introspectComments - Komentarze jako dokumentacja

Gdy introspectComments jest włączone, komentarze JSDoc stają się opisami w Swagger:

export class LegionDto {
  /**
   * Unikalna nazwa legionu w Imperium
   * @example 'Legio X Gemina'
   */
  name: string;

  /**
   * Prowincja stacjonowania
   * @example 'Pannonia'
   */
  province: string;

  /**
   * Liczba żołnierzy w legionie
   * @example 5000
   */
  soldiers: number;
}

Tag @example automatycznie generuje przykładową wartość w Swagger UI.

classValidatorShim - Integracja z walidacją

Gdy classValidatorShim jest włączony, dekoratory class-validator wpływają na dokumentację Swagger:

import { IsString, IsNumber, IsOptional, Min, Max, IsEnum } from 'class-validator';

export class CreateLegionaryDto {
  /** Imię legionisty */
  @IsString()
  name: string;

  /** Ranga w legionie */
  @IsEnum(LegionaryRank)
  @IsOptional()
  rank?: LegionaryRank;

  /** Lata doświadczenia */
  @IsNumber()
  @Min(0)
  @Max(40)
  experience: number;
}

Plugin automatycznie:

  • @IsOptional() oznacza pole jako required: false
  • @IsEnum() generuje listę dozwolonych wartości
  • @Min() / @Max() ustawia minimum / maximum
  • @IsString() potwierdza typ string

Kiedy nadal używać @ApiProperty?

CLI Plugin nie zastępuje wszystkich przypadków użycia @ApiProperty(). Nadal potrzebujesz go dla:

  • Zagnieżdżonych typów (type: () => AddressDto)
  • Tablic obiektów (type: [LegionaryDto])
  • Złożonych przykładów
  • Nadpisywania automatycznie wygenerowanych opisów

Ćwiczenie praktyczne

Skonfiguruj CLI Plugin i stwórz DTO z komentarzami JSDoc:

Kod do tej lekcji: src/nest-cli.config.ts
// Konfiguracja CLI Plugin @nestjs/swagger
// Ten plik przedstawia konfiguracje nest-cli.json

const nestCliConfig = {
  collection: "@nestjs/schematics",
  sourceRoot: "src",
  compilerOptions: {
    deleteOutDir: true,
    plugins: [
      {
        name: "@nestjs/swagger",
        options: {
          // TODO: Wlacz classValidatorShim (true)
          // TODO: Wlacz introspectComments (true)
          // TODO: Ustaw dtoFileNameSuffix na ['.dto.ts', '.entity.ts']
        }
      }
    ]
  }
};

console.log("=== nest-cli.json config ===");
console.log(JSON.stringify(nestCliConfig, null, 2));

// Przyklad DTO z komentarzami JSDoc (zamiast @ApiProperty)
class LegionaryDto {
  /** Unikalne imie legionisty
   * @example 'Marcus Aurelius'
   */
  name: string;

  /** Ranga w hierarchii legionu
   * @example 'Centurio'
   */
  rank?: string;

  /** Lata sluzby w legionie
   * @example 8
   */
  experience: number;

  /** Czy legionista jest aktywny w sluzbie
   * @example true
   */
  isActive: boolean;
}

console.log("");
console.log("Z CLI Plugin komentarze JSDoc staja sie opisami Swagger");
console.log("Tag @example generuje przykladowe wartosci");
console.log("Pola z ? sa automatycznie oznaczane jako opcjonalne");
console.log("classValidatorShim integruje walidacje z dokumentacja");

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 CLI Plugin @nestjs/swagger?

  2. 2. Co robi opcja introspectComments w CLI Plugin @nestjs/swagger?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Układanie w pionie

    Uporządkuj kroki włączania CLI Plugin od pliku konfiguracyjnego do efektu:

  • Edytor kodu

    Dodaj komentarze JSDoc z opisem i @example do każdego pola DTO

  • Układanie w poziomie

    Ułóż elementy komentarza JSDoc z tagiem @example:

  • Klikanie w kolejności

    Ułóż elementy konfiguracji plugina w nest-cli.json od zewnętrznego klucza do opcji:

  • Edytor kodu

    Stwórz SenatorResponseDto i CreateSenatorDto, następnie użyj ich jako type w dekoratorach odpowiedzi

  1. PytanieFunkcja CLI Plugin
  2. Ułóż w kolejnościKonfiguracja CLI Plugin
  3. Zadanie z kodemDTO z komentarzami JSDoc
  4. PytanieOpcja introspectComments
  5. Ułóż w kolejnościTag @example w JSDoc
  6. Kliknij w kolejnościKonfiguracja plugina w nest-cli.json
  7. PytanieOpcja classValidatorShim
  8. Zadanie z kodemDTO odpowiedzi z typem w kontrolerze

Przydatne artykuły