Installation et configuration de Swagger dans NestJS

Avant que nos chroniqueurs ne commencent à rédiger les annales, nous devons préparer les bons outils - parchemin, encre et sceaux impériaux. Dans NestJS, cela signifie installer le paquet @nestjs/swagger et configurer le module Swagger.

Installation du paquet

La première étape consiste à installer le paquet Swagger officiel pour NestJS :

1npm install @nestjs/swagger

Le paquet @nestjs/swagger contient tout ce dont nous avons besoin : les décorateurs, un module de configuration et l'intégration de Swagger UI.

DocumentBuilder - L'Architecte des Chroniques

DocumentBuilder est une classe qui permet de construire la configuration de la documentation d'API. Elle fonctionne comme un architecte qui conçoit la structure de nos annales :

1import { DocumentBuilder } from '@nestjs/swagger';
2
3const config = new DocumentBuilder()
4  .setTitle('Imperium Romanum API')
5  .setDescription('API documentation for managing the Roman Empire')
6  .setVersion('1.0')
7  .build();

Méthodes de DocumentBuilder

SwaggerModule.setup() - Ouvrir le Forum

Après avoir construit la configuration, nous devons « ouvrir le Forum » - c'est-à-dire rendre la documentation accessible à une URL spécifique :

1import { NestFactory } from '@nestjs/core';
2import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
3import { AppModule } from './app.module';
4
5async function bootstrap() {
6  const app = await NestFactory.create(AppModule);
7
8  // 1. Construire la configuration de la documentation
9  const config = new DocumentBuilder()
10    .setTitle('Imperium Romanum API')
11    .setDescription('API for managing provinces and legions of the Empire')
12    .setVersion('1.0')
13    .addTag('Legiones', 'Legion management')
14    .addTag('Provinciae', 'Province management')
15    .addTag('Tributum', 'Tax system')
16    .addBearerAuth()
17    .build();
18
19  // 2. Créer le document OpenAPI
20  const document = SwaggerModule.createDocument(app, config);
21
22  // 3. Servir Swagger UI au chemin /api/docs
23  SwaggerModule.setup('api/docs', app, document);
24
25  await app.listen(3000);
26}
27bootstrap();

Après le démarrage de l'application, Swagger UI sera accessible à l'adresse http://localhost:3000/api/docs.

Paramètres de SwaggerModule.setup()

La méthode setup() accepte quatre arguments :

1. path - le chemin URL de la documentation (par ex. 'api/docs')
2. app - l'instance de l'application NestJS
3. document - le document OpenAPI généré
4. options (facultatif) - options de configuration supplémentaires

1SwaggerModule.setup('api/docs', app, document, {
2  customSiteTitle: 'Chronicles of the Imperium API',
3  customfavIcon: '/favicon.ico',
4  swaggerOptions: {
5    persistAuthorization: true,
6    docExpansion: 'none',
7    filter: true,
8  },
9});

Configuration étendue de DocumentBuilder

Voici un exemple de configuration complète avec toutes les options :

1const config = new DocumentBuilder()
2  .setTitle('Imperium Romanum API')
3  .setDescription('Complete API documentation of the Roman Empire')
4  .setVersion('2.0')
5  .setContact('Caesar Augustus', 'https://imperium.rome', 'caesar@rome.gov')
6  .setLicense('MIT', 'https://opensource.org/licenses/MIT')
7  .addServer('http://localhost:3000', 'Development server')
8  .addServer('https://api.imperium.rome', 'Production server')
9  .addTag('Legiones', 'Legion management endpoints')
10  .addTag('Provinciae', 'Province management endpoints')
11  .addBearerAuth(
12    { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
13    'JWT-auth',
14  )
15  .build();

Exercice pratique

Configure Swagger dans le fichier main.ts du projet Imperium :

Retiens cette règle, jeune chroniqueur : DocumentBuilder dessine le contenu des annales - titre, version, tags et mode d'authentification - tandis que SwaggerModule.setup() ouvre le forum où chaque légionnaire consultera la documentation de ton API sans jamais avoir à t'interroger.

1// Configuration de Swagger dans main.ts
2import { NestFactory } from '@nestjs/core';
3import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
4
5async function bootstrap() {
6  // const app = await NestFactory.create(AppModule);
7
8  // TODO: Créer la configuration DocumentBuilder
9  // Utilise les méthodes : setTitle, setDescription, setVersion, addTag, build
10  const config = new DocumentBuilder()
11    .setTitle('Imperium Romanum API')
12    // TODO: Ajoute la description de l'API
13    // TODO: Définis la version à '1.0'
14    // TODO: Ajoute le tag 'Legiones' avec une description
15    // TODO: Ajoute le tag 'Provinciae' avec une description
16    .build();
17
18  // TODO: Créer le document OpenAPI
19  // const document = SwaggerModule.createDocument(app, config);
20
21  // TODO: Rends Swagger UI disponible au chemin 'api/docs'
22  // SwaggerModule.setup('api/docs', app, document);
23
24  // await app.listen(3000);
25  console.log("Swagger UI disponible sur : http://localhost:3000/api/docs");
26}
27
28bootstrap();
29
30// Exemple de configuration complète :
31console.log("=== DocumentBuilder ===");
32console.log("setTitle() - nom de la documentation");
33console.log("setDescription() - description du projet");
34console.log("setVersion() - version de l'API");
35console.log("addTag() - section (groupe d'endpoints)");
36console.log("addBearerAuth() - configuration JWT");
37console.log("build() - finalisation de la configuration");
38console.log("");
39console.log("=== SwaggerModule ===");
40console.log("createDocument(app, config) - génère la spec OpenAPI");
41console.log("setup(path, app, document) - lance Swagger UI");
42