Kurs NestJS · Moduł 11: Swagger i OpenAPI
Instalacja i konfiguracja Swagger w NestJS
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/swaggerPakiet @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
| 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:
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:
- path - ścieżka URL dokumentacji (np.
'api/docs') - app - instancja aplikacji NestJS
- document - wygenerowany dokument OpenAPI
- 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. Jaka klasa w @nestjs/swagger służy do budowania konfiguracji dokumentacji API?
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