diff --git a/README.md b/README.md index de5d4b1..89042cc 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,98 @@ -# n8n-nodes-openapi-node +# n8n OpenAPI Node -To install dependencies: +Custom n8n node that generates its UI and runtime behavior directly from an OpenAPI schema. Point it at any OpenAPI JSON document and the node will: + +- Fetch and cache the specification. +- Surface every operation as a selectable action inside n8n. +- Auto-populate query, path, header, and JSON body parameters. +- Execute requests with optional bearer-token authentication. + +## Prerequisites + +- n8n `^1.116.0` (self-hosted with custom nodes enabled). +- [Bun](https://bun.com) `^1.3.0` for local builds. +- Node.js 18+ (for running Bun and the build scripts). +- Access to an OpenAPI 3.x compliant JSON document. + +## Installation + +1. Clone or download this repository into your n8n custom modules folder (commonly `~/.n8n/custom/`). +2. Install dependencies: + + ```bash + bun install + ``` + +3. Build the distributable bundle: + + ```bash + bun run build + ``` + + The compiled node (TypeScript -> JavaScript and assets) is written to the `dist/` directory so n8n can consume it. + +4. Restart your n8n instance. The node appears as **OpenApiNode - Dynamic OpenAPI** in the node chooser. + +> Tip: n8n discovers custom nodes by folder name. Ensure the directory is called `n8n-nodes-openapi-node` when placed inside `~/.n8n/custom/`. + +## Using the Node + +### 1. Provide an OpenAPI document + +- Set **OpenAPI JSON URL** to a publicly reachable spec (e.g. `https://petstore3.swagger.io/api/v3/openapi.json`). +- The spec is cached in-memory during a workflow run to avoid repeated downloads. + +### 2. Choose an operation + +- After the spec loads, **Operation** lists every path/method pair, displaying the summary plus HTTP verb and route. +- The node builds the operation list dynamically at runtime, so updates to your spec are reflected on reload. + +### 3. Configure parameters + +- Use **Parameters (Form)** to add query, path, header, or body fields. +- Path parameters are required; the node validates they are present before executing. +- For JSON bodies, the node inspects the schema and offers body properties as selectable options. + +### 4. Optional credentials + +Create an **OpenApiNode (Bearer Token)** credential inside n8n and populate: + +- `Base URL` – default base API URL, used if the spec omits `servers`. +- `Bearer Token` – token value (the node adds the `Authorization: Bearer ...` header automatically). + +Alternatively, provide an `X-API-Key` header in the parameter form. + +### 5. Execute the workflow + +- GET/HEAD requests never send a body; other methods send JSON when body parameters exist. +- Responses are returned as-is in the node output (`resp.data` under `json`). +- When `Continue On Fail` is enabled, errors are forwarded as `{ error, message, response }`. + +## Development + +- Source TypeScript lives under `src/`; build artifacts under `dist/`. +- The build script (`bun run build`) compiles each entrypoint with Bun, minifies output, and copies static assets. +- Use `bun run publish` to bump versions, rebuild, and run the helper publish script (adjust it to your release flow). + +Common scripts: ```bash -bun install +bun run build # Clean build into dist/ +bun run version:update # Sync src/package.json version metadata ``` -To run: +## Project Structure -```bash -bun run index.ts -``` +- `src/nodes/OpenApiNode.node.ts` – main node definition, load-options logic, and request executor. +- `src/credentials/OpenApiCredential.credentials.ts` – bearer token credential used by the node. +- `bin/` – helper scripts for building, versioning, and publishing. +- `dist/` – generated output consumed by n8n (created after building). +## Troubleshooting -This project was created using `bun init` in bun v1.3.0. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime. +- **Spec fails to load**: ensure the URL is reachable from the n8n host and returns valid JSON. +- **Operations missing**: confirm the OpenAPI document sets `operationId` or the combination of method & path is unique. +- **401/403 responses**: verify the credential token is valid or add required headers via the parameter form. +- **Local specs**: host them behind a reachable URL (file paths are not yet supported). +Feel free to tailor the build or credential logic to match your API authentication needs. diff --git a/src/README.md b/src/README.md new file mode 100644 index 0000000..fc19db6 --- /dev/null +++ b/src/README.md @@ -0,0 +1,58 @@ +# n8n-nodes-openapi-node + +This is a dynamic n8n node that generates its user interface from an OpenAPI (formerly Swagger) specification. This allows you to interact with almost any REST API that provides an OpenAPI spec, without needing a dedicated n8n node for each service. + +## Features + +- **Dynamic UI Generation**: The node's fields for operations and parameters are created dynamically based on the provided OpenAPI specification URL. +- **Broad API Support**: Works with any API that has a valid OpenAPI v2 or v3 specification available via URL. +- **Parameter Handling**: Supports parameters in the `path`, `query`, `header`, and `body` (as JSON). +- **Authentication**: Uses Bearer Token authentication. The credential configuration allows you to set a Base URL and the token. +- **Spec Caching**: OpenAPI specifications are cached in memory to improve performance and reduce redundant requests when configuring multiple nodes or re-executing workflows. + +## Installation + +To install this custom node in your n8n instance: + +1. Go to **Settings > Community Nodes**. +2. Select **Install a community node**. +3. Enter `n8n-nodes-openapi-node` as the npm package name. +4. Agree to the risks and click **Install**. + +n8n will install the node and restart the instance. + +## Configuration + +### Credentials + +This node uses a credential type named **OpenApiNode (Bearer Token)**. + +1. Go to the **Credentials** section in n8n. +2. Click **Add credential**. +3. Search for `OpenApiNode (Bearer Token)` and select it. +4. Fill in the following fields: + - **Base URL**: The base URL of the API (e.g., `https://api.example.com`). This will be used if the OpenAPI spec does not specify a server URL. + - **Bearer Token**: Your API authentication token. Do not include the `Bearer ` prefix. + +### Node Properties + +1. **OpenAPI JSON URL**: Provide the public URL to the OpenAPI specification file (e.g., `https://petstore.swagger.io/v2/swagger.json`). The node will fetch this URL to build the list of operations. +2. **Operation**: Once the OpenAPI URL is provided, this dropdown will be populated with all the operations found in the specification. Select the API endpoint you wish to call. +3. **Parameters (Form)**: After selecting an operation, you can add the required parameters. + - Click **Add Parameter**. + - **Name**: Select the parameter name from the dropdown. This list is also generated from the spec and includes parameters from the path, query, headers, and request body. + - **In**: Specify where the parameter should be placed (`query`, `path`, `header`, or `body`). This is typically determined by the API, so ensure it matches the API's expectation. + - **Value**: The value for the parameter. + +## How It Works + +1. When you add the node to your workflow and provide an OpenAPI spec URL, the node fetches and parses the specification. +2. It extracts all the API paths and methods (`GET`, `POST`, etc.) and lists them in the **Operation** dropdown. +3. When you select an operation, the node identifies the parameters (path, query, body, etc.) associated with that operation. +4. You provide values for these parameters in the UI. +5. At execution time, the node constructs the full API request, including the URL, headers (with the Bearer Token from credentials), query parameters, and request body. +6. It then uses `axios` to make the HTTP request and returns the JSON response as the output. + +## License + +ISC