@algolia/n8n-openapi-node

@algolia/n8n-openapi-node

Turn Your OpenAPI (Swagger) spec into a n8n node!

• Quick Start
  • Installation
  • Usage
• Local usage
• How it works
  • Resource
  • Operation
  • Query Parameters
  • Request Body
  • Headers
• Customization
• Use Cases
• FAQ
  • I have only OpenAPI v2 spec, what can I do?
  • I have openapi.yaml spec, what can I do?
  • Why it doesn't work with my OpenAPI spec?

Quick Start

If you have an OpenAPI v3 specification, you can generate the properties for your n8n community node in minutes.

You still need to create and publish an n8n-nodes-<yourproject> package, but this library generates the node properties for you from your OpenAPI spec.

👉 We recommend using this template for n8n-nodes-<yourproject>:

• https://github.com/n8n-io/n8n-nodes-starter (official starter)

Find real-world examples in the Use Cases section.

Installation

Add @algolia/n8n-openapi-node as a dependency:

npm install @algolia/n8n-openapi-node
# OR
pnpm add @algolia/n8n-openapi-node
# OR
yarn add @algolia/n8n-openapi-node

Usage

• Put your openapi.json in your project (OpenAPI v3 JSON; see FAQ if you only have v2 or YAML).

• Generate the properties TypeScript file with this library and use it in your node definition.

Example generator script:

import { writeFileSync } from "fs";
import { generateN8NNodes } from "@algolia/n8n-openapi-node";

async function main() {
  const properties = await generateN8NNodes("path/of/your/spec/file.json");

  const nodeContent = `import { INodeProperties } from 'n8n-workflow';

  const properties: INodeProperties[] = ${JSON.stringify(properties, null, 2)};

  export default properties;
  `;

  fs.writeFileSync("destination/path/file.ts", nodeContent);
}

main();

Then in your node file:

import {
  INodeType,
  INodeTypeDescription,
  NodeConnectionType,
} from "n8n-workflow";
import properties from "./properties"; // generated file (default export)

export class Petstore implements INodeType {
  description: INodeTypeDescription = {
    displayName: "Petstore",
    name: "petstore",
    icon: "file:petstore.svg",
    group: ["transform"],
    version: 1,
    subtitle: '={{$parameter["operation"] + ": " + $parameter["resource"]}}',
    description: "Interact with Petstore API",
    defaults: {
      name: "Petstore",
    },
    inputs: [NodeConnectionType.Main],
    outputs: [NodeConnectionType.Main],
    credentials: [
      {
        name: "petstoreApi",
        required: false,
      },
    ],
    requestDefaults: {
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      baseURL: "={{$credentials.url}}",
    },
    properties, // <==== generated by this library
  };
}

Local usage

If you want to use it in your own local n8n-nodes package:

• In this directory, execute the following command:

npm link

• Then in your local n8n-package directory:

npm link @algolia/n8n-openapi-node

Use the config above to test it.

How it works

This library extracts a few entities from OpenAPI v3 and converts them into n8n node properties:

• Resource - a list of Tags from OpenAPI spec
• Operation - a list of Operations from OpenAPI spec (aka Actions in n8n)
• Query Parameters - a list of operation.parameters from OpenAPI spec
• Request Body - a list of operation.requestBody.content from OpenAPI spec (only for application/json)
• Headers - a list of operation.parameters from OpenAPI spec

Resource

Top-level OpenAPI tags become the n8n Resource options.

Operation

Operations under each path become n8n Operation options. Path templating parameters are mapped into the request URL as {{ $parameter.paramName }}.

Note: At the moment, only paths starting with /1/ are included. Adjust your spec accordingly.

Query Parameters

operation.parameters with in: query are converted into fields with appropriate routing to request.qs.

Request Body

operation.requestBody (first media type) is converted into n8n fields. Objects, arrays, oneOf, allOf, and additionalProperties are mapped into json, options, fixedCollection, or multiOptions as appropriate, with routing pre-configured for the request body. Nested structures are supported.

Headers

operation.parameters with in: header are converted into fields routed to request.headers.

Customization

At the moment, customization hooks (e.g., custom parsers or field overrides) are not exposed as a public API. If you need specific behaviors, please open an issue describing your use case.

FAQ

I have only OpenAPI v2 spec, what can I do?

Paste your OpenAPI 2.0 definition into https://editor.swagger.io and select Edit > Convert to OpenAPI 3 from the menu.

https://stackoverflow.com/a/59749691

I have openapi.yaml spec, what can I do?

Paste your yaml spec to https://editor.swagger.io and select File > Save as JSON from the menu.

Why it doesn't work with my OpenAPI spec?

Open a new issue and please attach your openapi.json file and describe the problem (logs are helpful too).