Kurs NestJS · Moduł 11: Swagger i OpenAPI
CLI Plugin - automatyczny skryba
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
| 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:
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 jakorequired: false@IsEnum()generuje listę dozwolonych wartości@Min()/@Max()ustawiaminimum/maximum@IsString()potwierdza typstring
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. Co robi CLI Plugin @nestjs/swagger?
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
Zadania po tej lekcji
- PytanieFunkcja CLI Plugin
- Ułóż w kolejnościKonfiguracja CLI Plugin
- Zadanie z kodemDTO z komentarzami JSDoc
- PytanieOpcja introspectComments
- Ułóż w kolejnościTag @example w JSDoc
- Kliknij w kolejnościKonfiguracja plugina w nest-cli.json
- PytanieOpcja classValidatorShim
- Zadanie z kodemDTO odpowiedzi z typem w kontrolerze