La création et la maintenance d'une documentation API claire et à jour sont essentielles pour toute application moderne. Dans l'écosystème NestJS, le module @nestjs/swagger offre une intégration robuste avec OpenAPI (anciennement Swagger), permettant de générer automatiquement une documentation interactive directement à partir du code de votre application. Cette documentation peut ensuite être consultée via une interface utilisateur (Swagger UI) et exportée pour être utilisée avec des outils tiers.

Pour commencer, installez les paquets nécessaires :

npm install @nestjs/swagger swagger-ui-express

Ensuite, enrichissez vos contrôleurs NestJS avec les décorateurs fournis par @nestjs/swagger. Ces décorateurs permettent de décrire les ressources, les opérations, les paramètres et les réponses de votre API.

Considérons un exemple de contrôleur pour la gestion de produits :

import { Controller, Get, Post, Body, HttpCode, HttpStatus } from '@nestjs/common';
import { ApiTags, ApiOperation, ApiBody, ApiResponse } from '@nestjs/swagger';

// Définition d'un DTO pour la création d'un produit, utilisé par @ApiBody
class CreationProduitDto {
 nom: string;
 prix: number;
 description?: string;
}

@Controller('produits')
@ApiTags('Produits') // Permet de regrouper les opérations sous une étiquette "Produits" dans la doc Swagger
export class ProduitsController {
 @Get()
 @HttpCode(HttpStatus.OK)
 @ApiOperation({ summary: 'Récupérer la liste de tous les produits disponibles' })
 @ApiResponse({
   status: HttpStatus.OK,
   description: 'Retourne un tableau des produits.',
   type: [CreationProduitDto], // Exemple de type de réponse
 })
 listerTousLesProduits(): CreationProduitDto[] {
   // Logique pour récupérer et retourner les produits
   return [{ nom: 'Produit A', prix: 29.99 }, { nom: 'Produit B', prix: 15.50 }];
 }

 @Post()
 @HttpCode(HttpStatus.CREATED)
 @ApiOperation({ summary: 'Créer un nouveau produit dans le catalogue' })
 @ApiBody({
   type: CreationProduitDto,
   description: 'Les détails du produit à ajouter au catalogue.',
 })
 @ApiResponse({
   status: HttpStatus.CREATED,
   description: 'Le produit a été créé avec succès.',
   type: CreationProduitDto,
 })
 @ApiResponse({
   status: HttpStatus.BAD_REQUEST,
   description: 'Données de produit invalides.',
 })
 ajouterProduit(@Body() nouveauProduit: CreationProduitDto): CreationProduitDto {
   // Logique pour ajouter le produit
   console.log('Produit reçu:', nouveauProduit);
   return { ...nouveauProduit, description: nouveauProduit.description || 'Description par défaut' };
 }
}

Pour rendre la documentation accessible, configurez le SwaggerModule dans le fichier principle de votre application (généralement main.ts) :

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
import { AppModule } from './app.module';

async function initialiserApplication() {
 const application = await NestFactory.create(AppModule);

 // Configuration du document OpenAPI
 const optionsDocumentation = new DocumentBuilder()
   .setTitle('API de Gestion du Catalogue')
   .setDescription('Cette API permet de gérer les articles et leurs propriétés.')
   .setVersion('1.0.0')
   .addTag('Produits', 'Opérations relatives aux articles disponibles en boutique')
   .addBearerAuth( // Exemple d'ajout d'une méthode d'authentification (jeton Bearer)
     { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
     'access-token'
   )
   .build();

 const specificationApi = SwaggerModule.createDocument(application, optionsDocumentation);

 // Activation de Swagger UI à l'URL '/api-docs'
 SwaggerModule.setup('api-docs', application, specificationApi);

 const portEcoute = 3002;
 await application.listen(portEcoute);
 console.log(`L'application NestJS est disponible sur http://localhost:${portEcoute}`);
 console.log(`La documentation OpenAPI est accessible via http://localhost:${portEcoute}/api-docs`);
}

initialiserApplication();

Après avoir démarré votre application, vous pouvez naviguer vers http://localhost:3002/api-docs (ou le port et le chemin que vous avez configurés) pour visualiser l'interface interactive Swagger UI. Cette interface vous permet de tester directement les endpoints de votre API.

Extraction de la Spécification OpenAPI (JSON/YAML)

Pour exporter la spécification OpenAPI générée, par exemple pour l'importer dans des outils de collaboration ou de test d'API comme Apidog, Postman, ou Insomnia, vous avez plusieurs options :

1. Via le Navigateur : Ouvrez les outils de développement de votre navigateur (F12 ou Ctrl+Maj+I), naviguez vers l'onglet "Réseau". Actualisez la page Swagger UI. Vous devriez voir une requête vers un fichier JSON ou YAML (souvent nommé swagger-json ou swagger-yaml, ou même inclus dans swagger-ui-init.js). Ouvrez cette ressource dans un nouvel onglet et enregistrez son contenu.
2. Accès Direct : Le module Swagger expose généralement la spécification à un endpoint par défaut. Souvent, la spécification JSON est accessible à http://localhost:3002/api-docs-json ou http://localhost:3002/api-docs/swagger-json (selon la version de @nestjs/swagger et votre configuration). Vous pouvez y accéder directement pour télécharger le fichier.

Intégration avec des Outils de Gestion d'API

Une fois le ficheir de spécification (JSON ou YAML) exporté, vous pouvez l'importer dans des plateformes comme Apidog.

Dans Apidog, par exemple, accédez aux paramètres de votre projet, puis recherchez l'option d'importation de données ou d'API. Sélectionnez "OpenAPI/Swagger" comme type d'importation. Vous pourrrez alors soit téléverser le fichier localement, soit fournir une URL si votre spécification est accessible publiquement. Apidog analysera et intégrera automatiquement vos définitions d'API, vous permettant de les tester, de les documenter davantage et de générer du code client ou serveur.