Kurs NestJS · Moduł 11: Swagger i OpenAPI

Instalacja i konfiguracja Swagger w NestJS

3 min czytania ·
W tej lekcji6

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:

npm 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:

import { DocumentBuilder } from '@nestjs/swagger';

const config = new DocumentBuilder()
  .setTitle('Imperium Romanum API')
  .setDescription('Dokumentacja API zarządzania Imperium Rzymskim')
  .setVersion('1.0')
  .build();

Metody DocumentBuilder

MetodaOpisPrzykł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 authOpcje bearer
setContact()Dane kontaktoweImię, URL, email
setLicense()Licencja APINazwa, URL
addServer()Serwer APIURL, 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:

import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // 1. Budujemy konfigurację dokumentacji
  const config = new DocumentBuilder()
    .setTitle('Imperium Romanum API')
    .setDescription('API do zarządzania prowincjami i legionami Imperium')
    .setVersion('1.0')
    .addTag('Legiones', 'Zarządzanie legionami')
    .addTag('Provinciae', 'Zarządzanie prowincjami')
    .addTag('Tributum', 'System podatkowy')
    .addBearerAuth()
    .build();

  // 2. Tworzymy dokument OpenAPI
  const document = SwaggerModule.createDocument(app, config);

  // 3. Udostępniamy Swagger UI pod ścieżką /api/docs
  SwaggerModule.setup('api/docs', app, document);

  await app.listen(3000);
}
bootstrap();

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
SwaggerModule.setup('api/docs', app, document, {
  customSiteTitle: 'Kroniki Imperium API',
  customfavIcon: '/favicon.ico',
  swaggerOptions: {
    persistAuthorization: true,
    docExpansion: 'none',
    filter: true,
  },
});

Rozbudowana konfiguracja DocumentBuilder

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

const config = new DocumentBuilder()
  .setTitle('Imperium Romanum API')
  .setDescription('Kompletna dokumentacja API Imperium Rzymskiego')
  .setVersion('2.0')
  .setContact('Cezar Augustus', 'https://imperium.rome', 'caesar@rome.gov')
  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
  .addServer('http://localhost:3000', 'Serwer deweloperski')
  .addServer('https://api.imperium.rome', 'Serwer produkcyjny')
  .addTag('Legiones', 'Endpointy zarządzania legionami')
  .addTag('Provinciae', 'Endpointy zarządzania prowincjami')
  .addBearerAuth(
    { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
    'JWT-auth',
  )
  .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.

Kod do tej lekcji: src/main.ts
// Konfiguracja Swagger w main.ts
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

async function bootstrap() {
  // const app = await NestFactory.create(AppModule);

  // TODO: Stworz konfiguracje DocumentBuilder
  // Uzyj metod: setTitle, setDescription, setVersion, addTag, build
  const config = new DocumentBuilder()
    .setTitle('Imperium Romanum API')
    // TODO: Dodaj opis API
    // TODO: Ustaw wersje na '1.0'
    // TODO: Dodaj tag 'Legiones' z opisem
    // TODO: Dodaj tag 'Provinciae' z opisem
    .build();

  // TODO: Stworz dokument OpenAPI
  // const document = SwaggerModule.createDocument(app, config);

  // TODO: Udostepnij Swagger UI pod sciezka 'api/docs'
  // SwaggerModule.setup('api/docs', app, document);

  // await app.listen(3000);
  console.log("Swagger UI dostepne pod: http://localhost:3000/api/docs");
}

bootstrap();

// Przykladowa pelna konfiguracja:
console.log("=== DocumentBuilder ===");
console.log("setTitle() - nazwa dokumentacji");
console.log("setDescription() - opis projektu");
console.log("setVersion() - wersja API");
console.log("addTag() - sekcja (grupa endpointow)");
console.log("addBearerAuth() - konfiguracja JWT");
console.log("build() - finalizacja konfiguracji");
console.log("");
console.log("=== SwaggerModule ===");
console.log("createDocument(app, config) - generuje OpenAPI spec");
console.log("setup(path, app, document) - uruchamia Swagger UI");

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. Jaka klasa w @nestjs/swagger służy do budowania konfiguracji dokumentacji API?

  2. 2. Jakie argumenty przyjmuje metoda SwaggerModule.setup() w minimalnej konfiguracji?

To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.

Zadania praktyczne w grze

  • Edytor kodu

    Uzupełnij konfigurację Swagger w main.ts dodając opis, wersję i tagi do DocumentBuilder

  • Układanie w poziomie

    Ułóż łańcuch metod DocumentBuilder w prawidłowej kolejności:

  • Klikanie w kolejności

    Ułóż kroki konfiguracji Swagger w main.ts we właściwej kolejności:

  • Edytor kodu

    Dodaj @ApiTags('Centuriones') do kontrolera i @ApiOperation z summary do metod

  1. PytanieKlasa DocumentBuilder
  2. PytanieMetoda SwaggerModule.setup
  3. Zadanie z kodemKonfiguracja Swagger w main.ts
  4. Ułóż w kolejnościŁańcuch metod DocumentBuilder
  5. Kliknij w kolejnościUruchomienie Swagger w NestJS
  6. PytanieMetoda addTag w DocumentBuilder
  7. Zadanie z kodemDodawanie tagów do kontrolera

Przydatne artykuły