node-red-contrib-openapi3

OpenAPI 3.0.3 documentation generator for Node-RED. Automatically creates Swagger UI documentation from http-in nodes in your flow.

Features

• ✅ Auto-discovery of http-in endpoints
• ✅ Visual editor for each endpoint
• ✅ Parameters (query, path, header, cookie)
• ✅ Request Body with inline schema or $ref
• ✅ Multiple Examples for Request/Response (dropdown in Swagger UI)
• ✅ Responses with any HTTP status codes
• ✅ Reusable Schemas
• ✅ Security schemes (API Key, Bearer, OAuth2, etc.)
• ✅ JSON validation for object/array types
• ✅ Exclude/Include endpoints
• ✅ Built-in Swagger UI

Installation

Via Node-RED Palette Manager

1. Open Node-RED
2. Menu → Manage palette → Install
3. Search for node-red-contrib-openapi3
4. Click Install

Via npm

cd ~/.node-red
npm install node-red-contrib-openapi3

Usage

1. Add swagger-doc node

1. Find swagger-doc node in the palette (Network section)
2. Drag it onto your flow
3. Double-click to configure

2. Configure global settings (settings.js)

module.exports = {
    // ... other settings
    
    openapi: {
        info: {
            title: "My API",
            version: "1.0.0",
            description: "API documentation"
        },
        servers: [
            { url: "http://localhost:1880", description: "Development" }
        ],
        components: {
            securitySchemes: {
                apiKey: {
                    type: "apiKey",
                    in: "header",
                    name: "X-API-Key"
                },
                bearerAuth: {
                    type: "http",
                    scheme: "bearer",
                    bearerFormat: "JWT"
                }
            },
            schemas: {
                Error: {
                    type: "object",
                    properties: {
                        statusCode: { type: "integer" },
                        error: { type: "string" },
                        message: { type: "string" }
                    }
                }
            }
        }
    }
};

3. Document your endpoints

Double-click swagger-doc node and fill in:

Info tab:

• Summary, Description, Tags
• Exclude (hide endpoint from docs)

Parameters tab:

• Query, Path, Header parameters

Request Body tab:

• Schema Properties (field types)
• Examples (variants for dropdown)

Responses tab:

• HTTP codes (200, 400, 401, etc.)
• Schema Properties
• Examples

Schemas tab:

• Reusable schemas ($ref)

Security tab:

• API Key, Bearer, OAuth2

4. Access documentation

After deploy:

• Swagger UI: http://localhost:1880/api-docs
• OpenAPI JSON: http://localhost:1880/api-docs/swagger.json

Examples

Simple GET endpoint

Parameters:
├── limit (query, integer, example: 10)
├── offset (query, integer, example: 0)
└── status (query, string, example: "active")

Response 200:
├── data (array)
├── total (integer)
└── limit (integer)

POST with Examples (RPC-style API)

Request Body Schema:
├── action (string, required)
└── params (object, required)

Request Examples:
├── getItems → {"action": "getItems", "params": {"id": 1}}
├── createItem → {"action": "create", "params": {"name": "test"}}
└── deleteItem → {"action": "delete", "params": {"id": 1}}

Swagger UI will show a dropdown to select examples.

Response with Examples

Response 200 Schema:
├── statusCode (integer)
├── data (array)
└── meta (object)

Response Examples:
├── successList → {"statusCode": 200, "data": [...], "meta": {...}}
└── emptyList → {"statusCode": 200, "data": [], "meta": {...}}

settings.js Options

| Option | Description | Default | |--------|-------------|---------| | openapi.info.title | API title | "Node-RED API" | | openapi.info.version | API version | "1.0.0" | | openapi.info.description | API description | "" | | openapi.servers | Server list | [] | | openapi.components.securitySchemes | Auth schemes | {} | | openapi.components.schemas | Global schemas | {} | | openapi.onlyDocumented | Show only documented endpoints | false |

Compatibility

• Node-RED: >= 2.0.0
• Node.js: >= 18.0.0
• OpenAPI: 3.0.3

License

Apache-2.0

Credits

Based on node-red-contrib-swagger by Steve Bassett.