Génération Swagger/OpenAPI pour JavaScript (Node.js) — outils et bibliothèques

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

Lors du développement d'une API REST avec Node.js, l'une des tâches clés est de créer une documentation claire et à jour. Swagger (maintenant OpenAPI) est devenu le standard de facto pour décrire les API. Dans cet article, nous allons examiner les principaux outils de génération automatique de spécifications OpenAPI dans les projets JavaScript (Node.js).

Qu'est-ce qu'OpenAPI et pourquoi le générer ?

OpenAPI est une spécification pour décrire les API RESTful au format JSON ou YAML. Elle permet de :

\n
• Créer automatiquement une documentation interactive (Swagger UI)
\n
• Générer des SDK clients pour différents langages
\n
• Effectuer la validation des requêtes et des réponses
\n
• Simplifier l'intégration entre les équipes
\n

La rédaction manuelle de la spécification est un processus laborieux qui devient rapidement obsolète. C'est pourquoi des outils ont été développés pour Node.js afin de générer OpenAPI à partir du code.

Principaux outils de génération OpenAPI dans Node.js

1. swagger-jsdoc

La bibliothèque la plus populaire, qui analyse les commentaires JSDoc dans le code et les transforme en spécification OpenAPI. Installation via npm :

npm install swagger-jsdoc swagger-ui-express

Exemple d'utilisation avec Express :

const swaggerJsdoc = require('swagger-jsdoc');\nconst swaggerUi = require('swagger-ui-express');\nconst express = require('express');\nconst app = express();\n\nconst options = {\n  definition: {\n    openapi: '3.0.0',\n    info: {\n      title: 'Mon API',\n      version: '1.0.0',\n      description: 'Exemple d\\'API avec génération de documentation'\n    },\n    servers: [\n      { url: 'http://localhost:3000' }\n    ]\n  },\n  apis: ['./routes/*.js'] // chemin vers les fichiers avec annotations\n};\n\nconst swaggerSpec = swaggerJsdoc(options);\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\n\n// Exemple de route avec annotation\n/**\n * @openapi\n * /users:\n *   get:\n *     summary: Obtenir la liste des utilisateurs\n *     tags: [Users]\n *     responses:\n *       200:\n *         description: Réponse réussie\n *         content:\n *           application/json:\n *             schema:\n *               type: array\n *               items:\n *                 $ref: '#/components/schemas/User'\n */\napp.get('/users', (req, res) => {\n  res.json([{ id: 1, name: 'Ivan' }]);\n});\n\napp.listen(3000);

2. swagger-autogen

Une alternative plus moderne, qui génère la spécification à partir des annotations dans les commentaires et détermine automatiquement les types de données. Installation :

npm install swagger-autogen

Exemple de script de génération :

const swaggerAutogen = require('swagger-autogen')();\n\nconst doc = {\n  info: {\n    title: 'Mon API',\n    description: 'Description de l\\'API'\n  },\n  host: 'localhost:3000',\n  schemes: ['http']\n};\n\nconst outputFile = './swagger-output.json';\nconst endpointsFiles = ['./app.js']; // fichier principal avec les routes\n\nswaggerAutogen(outputFile, endpointsFiles, doc).then(() => {\n  require('./app.js'); // démarrage du serveur après génération\n});

Dans les routes, il suffit d'ajouter un commentaire :

// #swagger.tags = ['Users']\n// #swagger.description = 'Endpoint pour obtenir les utilisateurs'\napp.get('/users', (req, res) => {\n  // #swagger.responses[200] = { description: 'Liste des utilisateurs' }\n  res.json([{ id: 1, name: 'Anna' }]);\n});

3. express-oas-generator

Une bibliothèque qui intercepte les requêtes et construit automatiquement la spécification OpenAPI à partir des données réelles. Adaptée aux prototypes :

npm install express-oas-generator

const express = require('express');\nconst expressOasGenerator = require('express-oas-generator');\nconst app = express();\n\nexpressOasGenerator.init(app, {}); // initialisation\n\napp.get('/products', (req, res) => {\n  res.json