Swagger/OpenAPI-Generierung für Node.js (JavaScript): Tools und Beispiele

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

Bei der Entwicklung moderner Webanwendungen mit Node.js ist die Erstellung einer verständlichen und aktuellen Dokumentation für die API eine der Hauptaufgaben. Swagger (OpenAPI) ist ein Standard zur Beschreibung von RESTful-Schnittstellen, der es ermöglicht, automatisch interaktive Dokumentation zu generieren, Anfragen zu testen und Verträge zwischen Client und Server zu pflegen. In diesem Artikel werden wir erläutern, wie die Generierung von Swagger/OpenAPI-Dokumentation für Node.js-Anwendungen mit beliebten Bibliotheken eingerichtet wird.

Was sind Swagger und OpenAPI?

Die OpenAPI Specification (früher bekannt als Swagger Specification) ist ein formaler Standard zur Beschreibung von HTTP-APIs. Sie ermöglicht:

• Die Definition von Endpunkten, Methoden, Parametern und Antworttypen.
• Die automatische Generierung von Client-SDKs.
• Die Erstellung interaktiver Dokumentation (Swagger UI).
• Die Validierung von Anfragen und Antworten.

Für Node.js gibt es mehrere Bibliotheken, die die Integration von OpenAPI vereinfachen. Wir betrachten die beiden beliebtesten: swagger-jsdoc und swagger-ui-express.

Bibliotheken zur Swagger-Generierung in Node.js

Die wichtigsten Werkzeuge:

• swagger-jsdoc — parst JSDoc-Kommentare im Code und erstellt daraus eine OpenAPI-Spezifikation.
• swagger-ui-express — zeigt die generierte Spezifikation als interaktive Webseite an.
• @nestjs/swagger (falls Sie NestJS verwenden) — Dekorateure für die automatische Generierung.

Wir konzentrieren uns auf die Kombination swagger-jsdoc + swagger-ui-express für Express.js.

Installation und Einrichtung

Installieren Sie die erforderlichen Pakete über npm:

npm install swagger-jsdoc swagger-ui-express

Erstellen Sie eine Datei swagger.js mit der Basiskonfiguration:

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: 'Beispiel-API mit automatischer Swagger-Generierung',        },        servers: [            { url: 'http://localhost:3000' },        ],    },    apis: ['./routes/*.js'], // Pfad zu den Dateien mit Endpunkten};

const swaggerSpec = swaggerJsdoc(options);

module.exports = { swaggerUi, swaggerSpec };

Hinzufügen von JSDoc-Kommentaren zu Endpunkten

Fügen Sie nun in Ihren Routendateien (z. B. routes/users.js) Kommentare im OpenAPI-Format hinzu:

/** * @openapi * /users: *   get: *     summary: Liste der Benutzer abrufen *     tags: [Users] *     parameters: *       - in: query *         name: limit *         schema: *           type: integer *         description: Anzahl der Benutzer (Standard 10) *     responses: *       200: *         description: Liste der Benutzer *         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);});

Definieren Sie analog das Datenmodell:

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

Einbindung von Swagger UI in Express

Fügen Sie in der Hauptdatei der Anwendung (app.js oder index.js) hinzu:

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