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

| Opcja | Opis | Domyślna | |-------|------|----------| |

classValidatorShim

| Automatycznie dodaje reguły walidacji z class-validator |

true

| |

introspectComments

| Używa komentarzy JSDoc jako opisów |

false

| |

dtoFileNameSuffix

| Jakie pliki analizować |

['.dto.ts', '.entity.ts']

| |

controllerFileNameSuffix

| Sufiks plików kontrolerów |

'.controller.ts'

| |

controllerKeyOfComment

| Klucz komentarza dla kontrolerów |

'description'

|

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: