Kurs NestJS · Moduł 11: Swagger i OpenAPI

Swagger UI customization - zdobienie Forum Annałów

3 min czytania ·
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:

OpcjaOpisDomyślna
persistAuthorizationZachowaj token JWT po odświeżeniufalse
docExpansionDomyślne rozwinięcie sekcji'list'
filterPokaż pole wyszukiwaniafalse
showRequestDurationPokaż czas odpowiedzifalse
tryItOutEnabledDomyślnie włączony tryb testowaniafalse
defaultModelsExpandDepthGłębokość rozwinięcia modeli1
defaultModelExpandDepthGłębokość rozwinięcia pól modelu1
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. 1. Co robi opcja persistAuthorization w swaggerOptions?

  2. 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

  1. PytanieOpcja persistAuthorization
  2. PytanieOpcja customSiteTitle
  3. Zadanie z kodemOpcje SwaggerModule.setup
  4. Ułóż w kolejnościKonfiguracja addBearerAuth
  5. PytanieOpcja docExpansion
  6. Zadanie z kodemPełny kontroler z dokumentacją

Przydatne artykuły