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

| Metoda | Opis | Przykład | |--------|------|---------| |

setTitle()

| Nazwa dokumentacji |

'Imperium API'

| |

setDescription()

| Opis projektu |

'API do zarządzania legionami'

| |

setVersion()

| Wersja API |

'1.0'

,

'2.3.1'

| |

addTag()

| Dodaje tag (sekcję) |

'Legiones'

| |

addBearerAuth()

| Konfiguruje JWT auth | Opcje bearer | |

setContact()

| Dane kontaktowe | Imię, URL, email | |

setLicense()

| Licencja API | Nazwa, URL | |

addServer()

| Serwer API | URL, opis | |

build()

| Finalizuje konfigurację | Zwraca OpenAPI object |

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: