Instalacja i konfiguracja Swagger w NestJS

Zanim nasi kronikarze rozpoczną spisywanie annałów, musimy przygotować odpowiednie narzędzia - pergamin, atrament i pieczęcie cesarskie. W NestJS oznacza to instalację pakietu @nestjs/swagger i konfigurację modułu Swagger.

Instalacja pakietu

Pierwszym krokiem jest zainstalowanie oficjalnego pakietu Swagger dla NestJS:

1npm install @nestjs/swagger

Pakiet @nestjs/swagger zawiera wszystko, czego potrzebujemy: dekoratory, moduł konfiguracyjny i integrację ze Swagger UI.

DocumentBuilder - Architekt Kronik

DocumentBuilder to klasa, która pozwala zbudować konfigurację dokumentacji API. Działa jak architekt, który projektuje strukturę naszych annałów:

1import { DocumentBuilder } from '@nestjs/swagger';
2
3const config = new DocumentBuilder()
4  .setTitle('Imperium Romanum API')
5  .setDescription('Dokumentacja API zarządzania Imperium Rzymskim')
6  .setVersion('1.0')
7  .build();

Metody DocumentBuilder

SwaggerModule.setup() - Otwarcie Forum

Po zbudowaniu konfiguracji, musimy "otworzyć Forum" - czyli udostępnić dokumentację pod określonym adresem URL:

1import { NestFactory } from '@nestjs/core';
2import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3import { AppModule } from './app.module';
4
5async function bootstrap() {
6  const app = await NestFactory.create(AppModule);
7
8  // 1. Budujemy konfigurację dokumentacji
9  const config = new DocumentBuilder()
10    .setTitle('Imperium Romanum API')
11    .setDescription('API do zarządzania prowincjami i legionami Imperium')
12    .setVersion('1.0')
13    .addTag('Legiones', 'Zarządzanie legionami')
14    .addTag('Provinciae', 'Zarządzanie prowincjami')
15    .addTag('Tributum', 'System podatkowy')
16    .addBearerAuth()
17    .build();
18
19  // 2. Tworzymy dokument OpenAPI
20  const document = SwaggerModule.createDocument(app, config);
21
22  // 3. Udostępniamy Swagger UI pod ścieżką /api/docs
23  SwaggerModule.setup('api/docs', app, document);
24
25  await app.listen(3000);
26}
27bootstrap();

Po uruchomieniu aplikacji, Swagger UI będzie dostępny pod adresem http://localhost:3000/api/docs.

Parametry SwaggerModule.setup()

Metoda setup() przyjmuje cztery argumenty:

1. path - ścieżka URL dokumentacji (np. 'api/docs')
2. app - instancja aplikacji NestJS
3. document - wygenerowany dokument OpenAPI
4. options (opcjonalne) - dodatkowe opcje konfiguracyjne

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Kroniki Imperium API',
3  customfavIcon: '/favicon.ico',
4  swaggerOptions: {
5    persistAuthorization: true,
6    docExpansion: 'none',
7    filter: true,
8  },
9});

Rozbudowana konfiguracja DocumentBuilder

Oto pełny przykład konfiguracji z wszystkimi opcjami:

1const config = new DocumentBuilder()
2  .setTitle('Imperium Romanum API')
3  .setDescription('Kompletna dokumentacja API Imperium Rzymskiego')
4  .setVersion('2.0')
5  .setContact('Cezar Augustus', 'https://imperium.rome', 'caesar@rome.gov')
6  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
7  .addServer('http://localhost:3000', 'Serwer deweloperski')
8  .addServer('https://api.imperium.rome', 'Serwer produkcyjny')
9  .addTag('Legiones', 'Endpointy zarządzania legionami')
10  .addTag('Provinciae', 'Endpointy zarządzania prowincjami')
11  .addBearerAuth(
12    { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
13    'JWT-auth',
14  )
15  .build();

Ćwiczenie praktyczne

Skonfiguruj Swagger w pliku main.ts projektu Imperium:

Zapamiętaj tę zasadę, młody kronikarzu: DocumentBuilder projektuje treść annałów, czyli tytuł, wersję, tagi i sposób uwierzytelniania, a SwaggerModule.setup() otwiera forum, na którym każdy legionista przeczyta dokumentację Twojego API bez pytania Ciebie o cokolwiek.

1// Konfiguracja Swagger w main.ts
2import { NestFactory } from '@nestjs/core';
3import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
4
5async function bootstrap() {
6  // const app = await NestFactory.create(AppModule);
7
8  // TODO: Stworz konfiguracje DocumentBuilder
9  // Uzyj metod: setTitle, setDescription, setVersion, addTag, build
10  const config = new DocumentBuilder()
11    .setTitle('Imperium Romanum API')
12    // TODO: Dodaj opis API
13    // TODO: Ustaw wersje na '1.0'
14    // TODO: Dodaj tag 'Legiones' z opisem
15    // TODO: Dodaj tag 'Provinciae' z opisem
16    .build();
17
18  // TODO: Stworz dokument OpenAPI
19  // const document = SwaggerModule.createDocument(app, config);
20
21  // TODO: Udostepnij Swagger UI pod sciezka 'api/docs'
22  // SwaggerModule.setup('api/docs', app, document);
23
24  // await app.listen(3000);
25  console.log("Swagger UI dostepne pod: http://localhost:3000/api/docs");
26}
27
28bootstrap();
29
30// Przykladowa pelna konfiguracja:
31console.log("=== DocumentBuilder ===");
32console.log("setTitle() - nazwa dokumentacji");
33console.log("setDescription() - opis projektu");
34console.log("setVersion() - wersja API");
35console.log("addTag() - sekcja (grupa endpointow)");
36console.log("addBearerAuth() - konfiguracja JWT");
37console.log("build() - finalizacja konfiguracji");
38console.log("");
39console.log("=== SwaggerModule ===");
40console.log("createDocument(app, config) - generuje OpenAPI spec");
41console.log("setup(path, app, document) - uruchamia Swagger UI");
42