OpenAPI Generator

@5minds/node-red-openapi-generator — Automatische OpenAPI 3.0-Dokumentation aus Node-RED HTTP-Nodes mit Swagger UI.

Überblick

Der OpenAPI Generator erstellt automatisch eine OpenAPI 3.0-Spezifikation aus Node-RED HTTP-In-Nodes. Die generierte Dokumentation ist über ein integriertes Swagger UI zugänglich.

npm-Paket: @5minds/node-red-openapi-generator Version: 1.1.x Lizenz: Proprietary

Config-Node

swagger-doc

Wird einem HTTP-In-Node zugeordnet, um Metadaten für die OpenAPI-Dokumentation zu definieren.

Konfiguration:

Eigenschaft	Typ	Beschreibung
`summary`	string	Kurzbeschreibung des Endpoints
`description`	string	Ausführliche Beschreibung
`tags`	string	Kommaseparierte Tags
`deprecated`	boolean	Endpoint als deprecated markieren
`parameters`	Array	Parameter-Definitionen
`requestBody`	Object	Request-Body-Spezifikation
`responses`	Object	Response-Definitionen

Parameter-Struktur:


{
  name: "orderId",
  in: "path",         // query, header, path, cookie
  required: true,
  description: "ID der Bestellung",
  schema: { type: "string" }
}

RequestBody-Struktur:


{
  description: "Bestelldaten",
  required: true,
  content: {
    "application/json": {
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          amount: { type: "number" }
        }
      }
    }
  }
}

Response-Struktur:


{
  "200": {
    description: "Erfolgreiche Antwort",
    content: {
      "application/json": {
        schema: { type: "object" }
      }
    }
  },
  "404": {
    description: "Nicht gefunden"
  }
}

HTTP-Endpunkte

Endpunkt	Beschreibung
`GET /http-api/swagger.json`	Generierte OpenAPI 3.0-Spezifikation
`GET /swagger-ui/swagger-ui.html`	Interaktive Swagger UI

Konfiguration in settings.js


openapi: {
  template: {
    openapi: "3.0.0",
    info: {
      title: "Meine API",
      version: "1.0.0",
      description: "API-Beschreibung"
    },
    servers: [
      { url: "https://api.example.com", description: "Produktion" }
    ],
    components: {
      schemas: {
        Order: {
          type: "object",
          properties: {
            id: { type: "string" },
            amount: { type: "number" }
          }
        }
      },
      securitySchemes: {
        bearerAuth: {
          type: "http",
          scheme: "bearer",
          bearerFormat: "JWT"
        }
      }
    }
  }
}

Verwendung

HTTP-In-Node erstellen (z.B. GET /api/orders)
swagger-doc Config-Node zuweisen
Metadaten konfigurieren (Summary, Parameters, Responses)
Deploy ausführen
Dokumentation unter /swagger-ui/swagger-ui.html aufrufen

Features

Automatische Erkennung: Findet alle HTTP-In-Nodes mit swagger-doc
Path-Parameter: Konvertiert Node-RED-Format (:param) zu OpenAPI ({param})
Reusable Components: Wiederverwendbare Schemas und Parameter
Security Schemes: OAuth2, Bearer Token, API Key
Tag-Gruppierung: Endpoints nach Tags gruppieren
Swagger UI: Integrierte interaktive Dokumentation

Beispiel


[HTTP-In: GET /api/orders/:id] → [Function: Query] → [HTTP-Response]
          ↑
   swagger-doc:
     summary: "Bestellung abrufen"
     parameters: [{name: "id", in: "path"}]
     responses: {200: {description: "Bestellung"}}

Installation

Im Enterprise Image enthalten. Keine separate Installation erforderlich.

Nächste Schritte

Engine Nodes — Engine-Integration
Authentication — API-Sicherheit