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:

| 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

|

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: