Swagger UI customization - zdobienie Forum Annałów

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

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Kroniki Imperium Romanum',
3  customCss: '.swagger-ui .topbar { background-color: #8B0000; }',
4  swaggerOptions: {
5    persistAuthorization: true,
6    docExpansion: 'none',
7    filter: true,
8    showRequestDuration: true,
9    tryItOutEnabled: true,
10  },
11});

customSiteTitle - Nazwa tablicy ogłoszeń

Zmienia tytuł strony w przeglądarce:

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Imperium API - Dokumentacja',
3});

customCss - Freski na ścianach

Pozwala dodać własne style CSS do Swagger UI:

1SwaggerModule.setup('api/docs', app, document, {
2  customCss: `
3    .swagger-ui .topbar { background-color: #8B0000; }
4    .swagger-ui .topbar-wrapper img { content: url('/logo.png'); }
5    .swagger-ui .info .title { color: #8B0000; }
6    .swagger-ui .btn.execute { background-color: #8B0000; }
7  `,
8});

swaggerOptions - Regulamin Forum

Opcje kontrolujące zachowanie Swagger UI:

1SwaggerModule.setup('api/docs', app, document, {
2  swaggerOptions: {
3    persistAuthorization: true,
4    docExpansion: 'none',
5    filter: true,
6    showRequestDuration: true,
7  },
8});

addBearerAuth - Konfiguracja autoryzacji

Pełna konfiguracja uwierzytelniania JWT w Swagger:

1const config = new DocumentBuilder()
2  .setTitle('Imperium API')
3  .addBearerAuth(
4    {
5      type: 'http',
6      scheme: 'bearer',
7      bearerFormat: 'JWT',
8      name: 'JWT',
9      description: 'Wpisz token JWT',
10      in: 'header',
11    },
12    'JWT-auth',
13  )
14  .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:

1const document = SwaggerModule.createDocument(app, config, {
2  operationIdFactory: (controllerKey: string, methodKey: string) =>
3    methodKey,
4});

Domyślnie NestJS generuje operationId w formacie ControllerName_methodName. Powyższe ustawienie użyje tylko nazwy metody.

Opcje createDocument

Metoda createDocument() przyjmuje dodatkowe opcje:

1const document = SwaggerModule.createDocument(app, config, {
2  // Uwzględnij tylko wybrane moduły
3  include: [LegionModule, ProvinceModule],
4
5  // Głębokość zagnieżdżenia schematów
6  deepScanRoutes: true,
7
8  // Własny generator operationId
9  operationIdFactory: (controllerKey, methodKey) => methodKey,
10
11  // Dodatkowe modele do uwzględnienia
12  extraModels: [ErrorResponseDto, PaginatedResponseDto],
13});

Zabezpieczenie dokumentacji

W środowisku produkcyjnym warto zabezpieczyć dostęp do Swagger UI:

1import * as basicAuth from 'express-basic-auth';
2
3// Przed SwaggerModule.setup()
4app.use(
5  '/api/docs',
6  basicAuth({
7    challenge: true,
8    users: { admin: 'imperiumSecret123' },
9  }),
10);
11
12SwaggerModule.setup('api/docs', app, document);

Ćwiczenie praktyczne

Skonfiguruj zaawansowane opcje Swagger UI dla projektu Imperium:

1// Swagger UI customization
2import { NestFactory } from '@nestjs/core';
3import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
4
5async function bootstrap() {
6  // const app = await NestFactory.create(AppModule);
7
8  const config = new DocumentBuilder()
9    .setTitle('Imperium Romanum API')
10    .setDescription('Kroniki API Imperium')
11    .setVersion('1.0')
12    // TODO: Dodaj addBearerAuth z pelna konfiguracja:
13    // type: 'http', scheme: 'bearer', bearerFormat: 'JWT'
14    .build();
15
16  // const document = SwaggerModule.createDocument(app, config);
17
18  // TODO: Skonfiguruj SwaggerModule.setup z opcjami:
19  // customSiteTitle: 'Kroniki Imperium API'
20  // swaggerOptions:
21  //   persistAuthorization: true
22  //   docExpansion: 'none'
23  //   filter: true
24  //   showRequestDuration: true
25
26  // SwaggerModule.setup('api/docs', app, document, {
27  //   // TODO: Dodaj customSiteTitle
28  //   // TODO: Dodaj swaggerOptions
29  // });
30
31  console.log("Swagger UI: http://localhost:3000/api/docs");
32}
33
34bootstrap();
35
36console.log("=== Opcje customizacji ===");
37console.log("customSiteTitle - tytul strony");
38console.log("customCss - wlasne style CSS");
39console.log("swaggerOptions.persistAuthorization - zachowaj token");
40console.log("swaggerOptions.docExpansion - rozwijanie sekcji");
41console.log("swaggerOptions.filter - pole wyszukiwania");
42console.log("swaggerOptions.showRequestDuration - czas odpowiedzi");
43