Swagger/OpenAPI-Generierung für JavaScript (Node.js) — Werkzeuge und Bibliotheken

Swagger/OpenAPI-Generierung für JavaScript (Node.js)

Bei der Entwicklung von REST-APIs in Node.js ist die Erstellung einer verständlichen und aktuellen Dokumentation eine der Hauptaufgaben. Swagger (jetzt OpenAPI) hat sich zum De-facto-Standard für die API-Beschreibung entwickelt. In diesem Artikel betrachten wir die wichtigsten Werkzeuge zur automatischen Generierung von OpenAPI-Spezifikationen in JavaScript-Projekten (Node.js).

Was ist OpenAPI und warum sollte man es generieren?

OpenAPI ist eine Spezifikation zur Beschreibung von RESTful-APIs im JSON- oder YAML-Format. Sie ermöglicht:

\n
• Automatische Erstellung interaktiver Dokumentation (Swagger UI)
\n
• Generierung von Client-SDKs für verschiedene Sprachen
\n
• Validierung von Anfragen und Antworten
\n
• Vereinfachung der Integration zwischen Teams
\n

Das manuelle Schreiben einer Spezifikation ist ein zeitaufwändiger Prozess, der schnell veraltet. Daher wurden für Node.js Werkzeuge entwickelt, die OpenAPI aus dem Code generieren.

Wichtige Werkzeuge zur OpenAPI-Generierung in Node.js

1. swagger-jsdoc

Die beliebteste Bibliothek, die JSDoc-Kommentare im Code parst und in eine OpenAPI-Spezifikation umwandelt. Installation über npm:

npm install swagger-jsdoc swagger-ui-express

Beispiel zur Verwendung mit 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: 'Meine API',\n      version: '1.0.0',\n      description: 'Beispiel-API mit Dokumentationsgenerierung'\n    },\n    servers: [\n      { url: 'http://localhost:3000' }\n    ]\n  },\n  apis: ['./routes/*.js'] // Pfad zu Dateien mit Annotationen\n};\n\nconst swaggerSpec = swaggerJsdoc(options);\napp.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));\n\n// Beispielroute mit Annotation\n/**\n * @openapi\n * /users:\n *   get:\n *     summary: Liste der Benutzer abrufen\n *     tags: [Users]\n *     responses:\n *       200:\n *         description: Erfolgreiche Antwort\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

Eine modernere Alternative, die die Spezifikation basierend auf Annotationen in Kommentaren generiert und Datentypen automatisch erkennt. Installation:

npm install swagger-autogen

Beispiel für ein Generierungsskript:

const swaggerAutogen = require('swagger-autogen')();\n\nconst doc = {\n  info: {\n    title: 'Meine API',\n    description: 'API-Beschreibung'\n  },\n  host: 'localhost:3000',\n  schemes: ['http']\n};\n\nconst outputFile = './swagger-output.json';\nconst endpointsFiles = ['./app.js']; // Hauptdatei mit Routen\n\nswaggerAutogen(outputFile, endpointsFiles, doc).then(() => {\n  require('./app.js'); // Serverstart nach Generierung\n});

In den Routen reicht ein Kommentar:

// #swagger.tags = ['Users']\n// #swagger.description = 'Endpunkt zum Abrufen von Benutzern'\napp.get('/users', (req, res) => {\n  // #swagger.responses[200] = { description: 'Benutzerliste' }\n  res.json([{ id: 1, name: 'Anna' }]);\n});

3. express-oas-generator

Eine Bibliothek, die Anfragen abfängt und automatisch eine OpenAPI-Spezifikation basierend auf tatsächlichen Daten erstellt. Geeignet für Prototypen:

npm install express-oas-generator

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