Kurs NestJS · Moduł 11: Swagger i OpenAPI
Swagger UI customization - zdobienie Forum Annałów
W tej lekcji9
Tak jak Forum Romanum było zdobione kolumnami, posągami i freskami, tak nasz Swagger UI można dostosować wizualnie i funkcjonalnie. NestJS oferuje wiele opcji personalizacji interfejsu dokumentacji.
Opcje SwaggerModule.setup()
Czwarty parametr metody setup() pozwala na zaawansowaną konfigurację:
SwaggerModule.setup('api/docs', app, document, {
customSiteTitle: 'Kroniki Imperium Romanum',
customCss: '.swagger-ui .topbar { background-color: #8B0000; }',
swaggerOptions: {
persistAuthorization: true,
docExpansion: 'none',
filter: true,
showRequestDuration: true,
tryItOutEnabled: true,
},
});customSiteTitle - Nazwa tablicy ogłoszeń
Zmienia tytuł strony w przeglądarce:
SwaggerModule.setup('api/docs', app, document, {
customSiteTitle: 'Imperium API - Dokumentacja',
});customCss - Freski na ścianach
Pozwala dodać własne style CSS do Swagger UI:
SwaggerModule.setup('api/docs', app, document, {
customCss: `
.swagger-ui .topbar { background-color: #8B0000; }
.swagger-ui .topbar-wrapper img { content: url('/logo.png'); }
.swagger-ui .info .title { color: #8B0000; }
.swagger-ui .btn.execute { background-color: #8B0000; }
`,
});swaggerOptions - Regulamin Forum
Opcje kontrolujące zachowanie Swagger UI:
| Opcja | Opis | Domyślna |
|---|---|---|
persistAuthorization | Zachowaj token JWT po odświeżeniu | false |
docExpansion | Domyślne rozwinięcie sekcji | 'list' |
filter | Pokaż pole wyszukiwania | false |
showRequestDuration | Pokaż czas odpowiedzi | false |
tryItOutEnabled | Domyślnie włączony tryb testowania | false |
defaultModelsExpandDepth | Głębokość rozwinięcia modeli | 1 |
defaultModelExpandDepth | Głębokość rozwinięcia pól modelu | 1 |
SwaggerModule.setup('api/docs', app, document, {
swaggerOptions: {
persistAuthorization: true,
docExpansion: 'none',
filter: true,
showRequestDuration: true,
},
});addBearerAuth - Konfiguracja autoryzacji
Pełna konfiguracja uwierzytelniania JWT w Swagger:
const config = new DocumentBuilder()
.setTitle('Imperium API')
.addBearerAuth(
{
type: 'http',
scheme: 'bearer',
bearerFormat: 'JWT',
name: 'JWT',
description: 'Wpisz token JWT',
in: 'header',
},
'JWT-auth',
)
.build();Po tej konfiguracji w Swagger UI pojawi się przycisk "Authorize", gdzie użytkownik może wpisać swój token JWT.
operationIdFactory - Nazwy operacji
Każda operacja w OpenAPI ma unikalny operationId. Możesz kontrolować jak są generowane:
const document = SwaggerModule.createDocument(app, config, {
operationIdFactory: (controllerKey: string, methodKey: string) =>
methodKey,
});Domyślnie NestJS generuje operationId w formacie ControllerName_methodName. Powyższe ustawienie użyje tylko nazwy metody.
Opcje createDocument
Metoda createDocument() przyjmuje dodatkowe opcje:
const document = SwaggerModule.createDocument(app, config, {
// Uwzględnij tylko wybrane moduły
include: [LegionModule, ProvinceModule],
// Głębokość zagnieżdżenia schematów
deepScanRoutes: true,
// Własny generator operationId
operationIdFactory: (controllerKey, methodKey) => methodKey,
// Dodatkowe modele do uwzględnienia
extraModels: [ErrorResponseDto, PaginatedResponseDto],
});Zabezpieczenie dokumentacji
W środowisku produkcyjnym warto zabezpieczyć dostęp do Swagger UI:
import * as basicAuth from 'express-basic-auth';
// Przed SwaggerModule.setup()
app.use(
'/api/docs',
basicAuth({
challenge: true,
users: { admin: 'imperiumSecret123' },
}),
);
SwaggerModule.setup('api/docs', app, document);Ćwiczenie praktyczne
Skonfiguruj zaawansowane opcje Swagger UI dla projektu Imperium:
Kod do tej lekcji: src/main.ts
// Swagger UI customization
import { NestFactory } from '@nestjs/core';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
async function bootstrap() {
// const app = await NestFactory.create(AppModule);
const config = new DocumentBuilder()
.setTitle('Imperium Romanum API')
.setDescription('Kroniki API Imperium')
.setVersion('1.0')
// TODO: Dodaj addBearerAuth z pelna konfiguracja:
// type: 'http', scheme: 'bearer', bearerFormat: 'JWT'
.build();
// const document = SwaggerModule.createDocument(app, config);
// TODO: Skonfiguruj SwaggerModule.setup z opcjami:
// customSiteTitle: 'Kroniki Imperium API'
// swaggerOptions:
// persistAuthorization: true
// docExpansion: 'none'
// filter: true
// showRequestDuration: true
// SwaggerModule.setup('api/docs', app, document, {
// // TODO: Dodaj customSiteTitle
// // TODO: Dodaj swaggerOptions
// });
console.log("Swagger UI: http://localhost:3000/api/docs");
}
bootstrap();
console.log("=== Opcje customizacji ===");
console.log("customSiteTitle - tytul strony");
console.log("customCss - wlasne style CSS");
console.log("swaggerOptions.persistAuthorization - zachowaj token");
console.log("swaggerOptions.docExpansion - rozwijanie sekcji");
console.log("swaggerOptions.filter - pole wyszukiwania");
console.log("swaggerOptions.showRequestDuration - czas odpowiedzi");
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 opcja persistAuthorization w swaggerOptions?
2. Co zmienia opcja customSiteTitle w konfiguracji SwaggerModule.setup()?
To 2 z 3 pytań do tej lekcji. Pozostałe rozwiążesz w grze.
Zadania praktyczne w grze
- Edytor kodu
Uzupełnij opcje SwaggerModule.setup z customSiteTitle i swaggerOptions
- Układanie w poziomie
Ułóż elementy konfiguracji addBearerAuth w prawidłowej kolejności:
- Edytor kodu
Dodaj pełną dokumentację Swagger (tags, operation, params, responses, auth) do kontrolera gladiatorów