Génération Swagger/OpenAPI pour Node.js (JavaScript) : outils et exemples

Génération Swagger/OpenAPI pour Node.js (JavaScript)

Lors du développement d'applications web modernes avec Node.js, l'une des tâches clés est la création d'une documentation claire et à jour pour l'API. Swagger (OpenAPI) est un standard de description des interfaces RESTful qui permet de générer automatiquement une documentation interactive, de tester les requêtes et de maintenir les contrats entre le client et le serveur. Dans cet article, nous allons voir comment configurer la génération de documentation Swagger/OpenAPI pour les applications Node.js à l'aide de bibliothèques populaires.

Qu'est-ce que Swagger et OpenAPI ?

La spécification OpenAPI (anciennement connue sous le nom de spécification Swagger) est un standard formel pour décrire les API HTTP. Elle permet de :

• Définir les endpoints, méthodes, paramètres et types de réponses.
• Générer automatiquement des SDK clients.
• Créer une documentation interactive (Swagger UI).
• Valider les requêtes et les réponses.

Pour Node.js, il existe plusieurs bibliothèques qui simplifient l'intégration d'OpenAPI. Examinons les deux plus populaires : swagger-jsdoc et swagger-ui-express.

Bibliothèques pour la génération Swagger dans Node.js

Les principaux outils :

• swagger-jsdoc — analyse les commentaires JSDoc dans le code et en assemble une spécification OpenAPI.
• swagger-ui-express — affiche la spécification générée sous forme de page web interactive.
• @nestjs/swagger (si vous utilisez NestJS) — décorateurs pour la génération automatique.

Nous nous concentrerons sur la combinaison swagger-jsdoc + swagger-ui-express pour Express.js.

Installation et configuration

Installez les paquets nécessaires via npm :

npm install swagger-jsdoc swagger-ui-express

Créez un fichier swagger.js avec la configuration de base :

const swaggerJsdoc = require('swagger-jsdoc');const swaggerUi = require('swagger-ui-express');

const options = {    definition: {        openapi: '3.0.0',        info: {            title: 'My Node.js API',            version: '1.0.0',            description: 'Exemple d\\'API avec génération automatique Swagger',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // chemin vers les fichiers avec les endpoints};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Ajout de commentaires JSDoc aux endpoints

Maintenant, dans vos fichiers de routes (par exemple, routes/users.js), ajoutez des commentaires au format OpenAPI :

/** * @openapi * /users: *   get: *     summary: Obtenir la liste des utilisateurs *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: Nombre d'utilisateurs (par défaut 10) *     responses: *       200: *         description: Liste des utilisateurs *         content: *           application/json: *             schema: *               type: array *               items: *                 $ref: '#/components/schemas/User' */router.get('/users', async (req, res) => {    const users = await getUsers(req.query.limit || 10);    res.json(users);});

Définissez de la même manière le modèle de données :

/** * @openapi * components: *   schemas: *     User: *       type: object *       properties: *         id: *           type: integer *         name: *           type: string *         email: *           type: string */

Connexion de Swagger UI à Express

Dans le fichier principal de l'application (app.js ou index.js), ajoutez :

const express = require('express');const { swaggerUi,