CLI Plugin - automatyczny skryba

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:

1// Bez CLI Plugin - dużo powtarzalnego kodu
2export class CreateLegionaryDto {
3  @ApiProperty({ description: 'Imię legionisty' })
4  name: string;
5
6  @ApiProperty({ description: 'Ranga', required: false })
7  rank?: string;
8
9  @ApiProperty({ description: 'Doświadczenie' })
10  experience: number;
11
12  @ApiProperty({ description: 'Czy aktywny' })
13  isActive: boolean;
14}

CLI Plugin - automatyczne generowanie

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

1// Z CLI Plugin - czysty kod, automatyczna dokumentacja
2export class CreateLegionaryDto {
3  /** Imię legionisty */
4  name: string;
5
6  /** Ranga w legionie */
7  rank?: string;
8
9  /** Lata doświadczenia */
10  experience: number;
11
12  /** Czy legionista jest aktywny */
13  isActive: boolean;
14}

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:

1{
2  "collection": "@nestjs/schematics",
3  "sourceRoot": "src",
4  "compilerOptions": {
5    "deleteOutDir": true,
6    "plugins": [
7      {
8        "name": "@nestjs/swagger",
9        "options": {
10          "classValidatorShim": true,
11          "introspectComments": true,
12          "dtoFileNameSuffix": [".dto.ts", ".entity.ts"]
13        }
14      }
15    ]
16  }
17}

Opcje CLI Plugin

introspectComments - Komentarze jako dokumentacja

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

1export class LegionDto {
2  /**
3   * Unikalna nazwa legionu w Imperium
4   * @example 'Legio X Gemina'
5   */
6  name: string;
7
8  /**
9   * Prowincja stacjonowania
10   * @example 'Pannonia'
11   */
12  province: string;
13
14  /**
15   * Liczba żołnierzy w legionie
16   * @example 5000
17   */
18  soldiers: number;
19}

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:

1import { IsString, IsNumber, IsOptional, Min, Max, IsEnum } from 'class-validator';
2
3export class CreateLegionaryDto {
4  /** Imię legionisty */
5  @IsString()
6  name: string;
7
8  /** Ranga w legionie */
9  @IsEnum(LegionaryRank)
10  @IsOptional()
11  rank?: LegionaryRank;
12
13  /** Lata doświadczenia */
14  @IsNumber()
15  @Min(0)
16  @Max(40)
17  experience: number;
18}

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:

1// Konfiguracja CLI Plugin @nestjs/swagger
2// Ten plik przedstawia konfiguracje nest-cli.json
3
4const nestCliConfig = {
5  collection: "@nestjs/schematics",
6  sourceRoot: "src",
7  compilerOptions: {
8    deleteOutDir: true,
9    plugins: [
10      {
11        name: "@nestjs/swagger",
12        options: {
13          // TODO: Wlacz classValidatorShim (true)
14          // TODO: Wlacz introspectComments (true)
15          // TODO: Ustaw dtoFileNameSuffix na ['.dto.ts', '.entity.ts']
16        }
17      }
18    ]
19  }
20};
21
22console.log("=== nest-cli.json config ===");
23console.log(JSON.stringify(nestCliConfig, null, 2));
24
25// Przyklad DTO z komentarzami JSDoc (zamiast @ApiProperty)
26class LegionaryDto {
27  /** Unikalne imie legionisty
28   * @example 'Marcus Aurelius'
29   */
30  name: string;
31
32  /** Ranga w hierarchii legionu
33   * @example 'Centurio'
34   */
35  rank?: string;
36
37  /** Lata sluzby w legionie
38   * @example 8
39   */
40  experience: number;
41
42  /** Czy legionista jest aktywny w sluzbie
43   * @example true
44   */
45  isActive: boolean;
46}
47
48console.log("");
49console.log("Z CLI Plugin komentarze JSDoc staja sie opisami Swagger");
50console.log("Tag @example generuje przykladowe wartosci");
51console.log("Pola z ? sa automatycznie oznaczane jako opcjonalne");
52console.log("classValidatorShim integruje walidacje z dokumentacja");
53