Personnalisation de Swagger UI - Décorer le Forum des Annales

Tout comme le Forum Romanum était décoré de colonnes, de statues et de fresques, notre Swagger UI peut être personnalisé visuellement et fonctionnellement. NestJS offre de nombreuses options pour personnaliser l'interface de la documentation.

Options de SwaggerModule.setup()

Le quatrième paramètre de la méthode setup() permet une configuration avancée :

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Chronicles of 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 - Nom du panneau d'affichage

Change le titre de la page dans le navigateur :

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

customCss - Fresques sur les murs

Permet d'ajouter des styles CSS personnalisés à 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 - Règlement du Forum

Options contrôlant le comportement de 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 - Configuration de l'autorisation

Configuration complète de l'authentification JWT dans 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: 'Enter JWT token',
10      in: 'header',
11    },
12    'JWT-auth',
13  )
14  .build();

Après cette configuration, un bouton « Authorize » apparaîtra dans Swagger UI où l'utilisateur pourra saisir son token JWT.

operationIdFactory - Noms des opérations

Chaque opération dans OpenAPI a un operationId unique. Tu peux contrôler la manière dont ils sont générés :

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

Par défaut, NestJS génère operationId au format ControllerName_methodName. Le réglage ci-dessus utilisera uniquement le nom de la méthode.

Options de createDocument

La méthode createDocument() accepte des options supplémentaires :

1const document = SwaggerModule.createDocument(app, config, {
2  // Inclure uniquement les modules sélectionnés
3  include: [LegionModule, ProvinceModule],
4
5  // Profondeur d'imbrication des schémas
6  deepScanRoutes: true,
7
8  // Générateur d'operationId personnalisé
9  operationIdFactory: (controllerKey, methodKey) => methodKey,
10
11  // Modèles supplémentaires à inclure
12  extraModels: [ErrorResponseDto, PaginatedResponseDto],
13});

Sécuriser la documentation

Dans un environnement de production, il est utile de sécuriser l'accès à Swagger UI :

1import * as basicAuth from 'express-basic-auth';
2
3// Avant 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);

Exercice pratique

Configure les options avancées de Swagger UI pour le projet Imperium :

1// Personnalisation de Swagger UI
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('Imperium API Chronicles')
11    .setVersion('1.0')
12    // TODO: Ajoute addBearerAuth avec la configuration complète :
13    // type: 'http', scheme: 'bearer', bearerFormat: 'JWT'
14    .build();
15
16  // const document = SwaggerModule.createDocument(app, config);
17
18  // TODO: Configure SwaggerModule.setup avec les options :
19  // customSiteTitle: 'Imperium API Chronicles'
20  // swaggerOptions:
21  //   persistAuthorization: true
22  //   docExpansion: 'none'
23  //   filter: true
24  //   showRequestDuration: true
25
26  // SwaggerModule.setup('api/docs', app, document, {
27  //   // TODO: Ajoute customSiteTitle
28  //   // TODO: Ajoute swaggerOptions
29  // });
30
31  console.log("Swagger UI: http://localhost:3000/api/docs");
32}
33
34bootstrap();
35
36console.log("=== Options de personnalisation ===");
37console.log("customSiteTitle - titre de la page");
38console.log("customCss - styles CSS personnalisés");
39console.log("swaggerOptions.persistAuthorization - conserve le token");
40console.log("swaggerOptions.docExpansion - expansion des sections");
41console.log("swaggerOptions.filter - champ de recherche");
42console.log("swaggerOptions.showRequestDuration - temps de réponse");
43