Używamy cookies, żeby zwiększyć Twoje doświadczenia na stronie

Logowanie/Rejestracja->

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:

Przejdź do CodeWorlds→