Import OpenAPI specifications and auto-generate API calls with schema validation and documentation.

OpenAPI Node

Import OpenAPI (Swagger) specifications to automatically generate API integrations with built-in validation, documentation, and operation discovery in Axellero workflows.

Features

Specification Import: Load OpenAPI 3.x and Swagger 2.x specifications
Auto-generated Operations: Automatic endpoint discovery and method generation
Schema Validation: Request/response validation against OpenAPI schemas
Authentication Integration: Support for all OpenAPI security schemes
Parameter Auto-completion: Suggestions based on specification
Documentation Integration: Built-in API documentation from specification

API-First Development

OpenAPI nodes enable API-first development by importing API specifications and automatically generating type-safe, validated integrations without manual configuration.

Specification Import

Import and configure OpenAPI/Swagger specifications

Operation Discovery

Explore and execute auto-discovered API operations

Schema Validation

Validate requests and responses against OpenAPI schemas

Security Configuration

Configure authentication based on OpenAPI security definitions

Specification Import

Import OpenAPI specifications from URLs, files, or specification registries:

Parameter	Type	Required	Description
`specificationUrl`	TEXT	Yes	URL or path to OpenAPI specification (`.json` or `.yaml`)
`specificationVersion`	AUTO	No	Automatically detected (`2.0`, `3.0.x`, `3.1.x`)
`serverIndex`	INT	No	Server index to use from `servers` array (default: `0`)
`customServer`	TEXT	No	Override server URL from specification
`validateSpec`	BOOLEAN	No	Validate specification syntax (default: `true`)

Public API Specification

{
  "specificationUrl": "https://petstore3.swagger.io/api/v3/openapi.json",
  "serverIndex": 0,
  "validateSpec": true
}

Private API with Custom Server

{
  "specificationUrl": "https://api.company.com/v2/openapi.yaml",
  "customServer": "https://staging.api.company.com",
  "validateSpec": true,
  "headers": {
    "Authorization": "Bearer {{ctx.consts.SPEC_ACCESS_TOKEN}}"
  }
}

Local Specification File

{
  "specificationUrl": "file:///path/to/api/specification.yaml",
  "customServer": "https://localhost:3000",
  "specificationVersion": "3.0.3"
}

Enterprise API Registry

{
  "specificationUrl": "https://registry.company.com/apis/customer-service/v2.1/spec.json",
  "serverIndex": 1,
  "registryAuth": {
    "type": "bearer",
    "token": "{{ctx.consts.REGISTRY_TOKEN}}"
  }
}

Security Configuration

Automatic Security Detection

OpenAPI nodes automatically detect and configure security schemes defined in the specification, including API keys, OAuth2, Bearer tokens, and HTTP Basic authentication.

API Key Authentication

OpenAPI Specification:

securitySchemes:
  ApiKeyAuth:
    type: apiKey
    in: header
    name: X-API-Key

Node Configuration:

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "security": {
    "ApiKeyAuth": "{{ctx.consts.API_KEY}}"
  }
}

OpenAPI Specification:

securitySchemes:
  ApiKeyQuery:
    type: apiKey
    in: query
    name: apikey

Node Configuration:

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "security": {
    "ApiKeyQuery": "{{ctx.consts.API_KEY}}"
  }
}

OAuth2 Integration

# OpenAPI Specification  
securitySchemes:
  OAuth2:
    type: oauth2
    flows:
      authorizationCode:
        authorizationUrl: https://api.example.com/oauth/authorize
        tokenUrl: https://api.example.com/oauth/token
        scopes:
          read: Read access
          write: Write access

Node Configuration:

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "security": {
    "OAuth2": {
      "accessToken": "{{ctx.vars.accessToken}}",
      "refreshToken": "{{ctx.vars.refreshToken}}",
      "scopes": ["read", "write"]
    }
  }
}

HTTP Bearer Token

# OpenAPI Specification
securitySchemes:
  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Node Configuration:

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "security": {
    "BearerAuth": "{{ctx.consts.JWT_TOKEN}}"
  }
}

Multiple Security Schemes

{
  "specificationUrl": "https://enterprise.api.com/openapi.json",
  "security": {
    "ApiKeyAuth": "{{ctx.consts.API_KEY}}",
    "BearerAuth": "{{ctx.vars.sessionToken}}",
    "BasicAuth": {
      "username": "{{ctx.consts.USERNAME}}",
      "password": "{{ctx.consts.PASSWORD}}"
    }
  }
}

Operation Discovery

Automatic Operation Detection

OpenAPI nodes automatically discover all available operations from the specification:

Available Operations (from Petstore API):

GET /pets - List all pets
POST /pets - Create a pet
GET /pets/{petId} - Get specific pet
DELETE /pets/{petId} - Delete a pet

Operation Execution

Execute discovered operations with automatic parameter validation:

Operation: GET /pets

{
  "operationId": "listPets",
  "parameters": {
    "query": {
      "limit": "{{ctx.vars.pageSize || 20}}",
      "offset": "{{ctx.vars.pageOffset || 0}}",
      "category": "{{ctx.vars.petCategory}}"
    }
  }
}

Operation: POST /pets

{
  "operationId": "createPet",
  "parameters": {
    "body": {
      "name": "{{ctx.nodes.petForm.outputs.name}}",
      "category": {
        "id": "{{ctx.nodes.categorySelector.outputs.id}}",
        "name": "{{ctx.nodes.categorySelector.outputs.name}}"
      },
      "photoUrls": ["{{ctx.nodes.imageUpload.outputs.imageUrl}}"],
      "tags": "{{ctx.vars.selectedTags}}",
      "status": "available"
    }
  }
}

Operation: GET /pets/{petId}

{
  "operationId": "getPetById",
  "parameters": {
    "path": {
      "petId": "{{ctx.vars.selectedPetId}}"
    },
    "headers": {
      "Accept": "application/json"
    }
  }
}

Complex Parameter Binding

Handle complex parameter structures defined in OpenAPI schemas:

Operation: POST /users/{userId}/orders

{
  "operationId": "createUserOrder",
  "parameters": {
    "path": {
      "userId": "{{ctx.user.id}}"
    },
    "body": {
      "orderId": "{{ctx.nodes.orderGenerator.outputs.id}}",
      "items": [
        {
          "productId": "{{ctx.vars.product.id}}",
          "quantity": "{{ctx.vars.product.quantity}}",
          "unitPrice": "{{ctx.vars.product.price}}",
          "customOptions": "{{ctx.vars.product.customizations}}"
        }
      ],
      "shippingAddress": {
        "street": "{{ctx.user.attrs.address.street}}",
        "city": "{{ctx.user.attrs.address.city}}",
        "zipCode": "{{ctx.user.attrs.address.zip}}",
        "country": "{{ctx.user.attrs.country}}"
      },
      "paymentMethod": "{{ctx.vars.selectedPaymentMethod}}",
      "metadata": {
        "source": "axellero-workflow",
        "workspaceId": "{{ctx.workspace_id}}",
        "timestamp": "{{ctx.nodes.timer.outputs.currentTime}}"
      }
    }
  }
}

Schema Validation

Request Validation

Automatic Validation

All requests are automatically validated against the OpenAPI schema before execution, preventing invalid API calls and providing detailed validation errors.

Validation Example:

{
  "operationId": "updatePet",
  "parameters": {
    "path": {
      "petId": "{{ctx.vars.petId}}"
    },
    "body": {
      "name": "{{ctx.nodes.form.outputs.petName}}",
      "status": "{{ctx.vars.petStatus}}"
    }
  },
  "validation": {
    "strict": true,
    "allowAdditionalProperties": false,
    "validateRequired": true
  }
}

Validation Errors:

{
  "validationErrors": [
    {
      "field": "body.name",
      "message": "Required field 'name' is missing",
      "schemaPath": "#/components/schemas/Pet/properties/name"
    },
    {
      "field": "parameters.path.petId",
      "message": "Expected integer, received string",
      "schemaPath": "#/paths/~1pets~1{petId}/put/parameters/0"
    }
  ],
  "success": false
}

Response Validation

{
  "operationId": "getPet",
  "responseValidation": {
    "enabled": true,
    "strictMode": false,
    "logValidationErrors": true
  }
}

Workflow Context Integration

📖 Reference

For context documentation, see the Workflow Context reference.

Dynamic Operation Selection

Choose operations based on workflow conditions:

{
  "operationId": "{{ctx.vars.action === 'create' ? 'createPet' : 'updatePet'}}",
  "parameters": {
    "path": {
      "petId": "{{ctx.vars.action === 'update' ? ctx.vars.existingPetId : null}}"
    },
    "body": {
      "name": "{{ctx.nodes.petForm.outputs.name}}",
      "category": "{{ctx.nodes.categoryForm.outputs.category}}",
      "status": "{{ctx.vars.defaultStatus}}"
    }
  }
}

User-scoped Operations

Include user context in API operations:

{
  "operationId": "getUserOrders",
  "parameters": {
    "path": {
      "userId": "{{ctx.user.id}}"
    },
    "query": {
      "startDate": "{{ctx.vars.dateRange.start}}",
      "endDate": "{{ctx.vars.dateRange.end}}",
      "status": "{{ctx.vars.orderStatus}}",
      "workspace": "{{ctx.workspace_slug}}"
    },
    "headers": {
      "X-User-Role": "{{ctx.user.roles[0]}}",
      "X-Workspace-ID": "{{ctx.workspace_id}}"
    }
  }
}

Conditional Parameters

Include parameters based on permissions or workflow state:

{
  "operationId": "getUsers",
  "parameters": {
    "query": {
      "limit": "{{ctx.vars.pageSize}}",
      "includePrivate": "{{ctx.user.roles.includes('admin')}}",
      "includeDeleted": "{{ctx.user.roles.includes('superadmin') && ctx.vars.showDeleted}}",
      "workspaceFilter": "{{ctx.vars.crossWorkspace ? null : ctx.workspace_id}}"
    }
  }
}

Response Processing

Success Response with Schema

{
  "operationResponse": {
    "statusCode": 200,
    "headers": {
      "content-type": "application/json",
      "x-rate-limit-remaining": "99"
    },
    "data": {
      "id": 12345,
      "name": "Fluffy",
      "category": {
        "id": 1,
        "name": "Cats"
      },
      "photoUrls": [
        "https://example.com/photos/fluffy.jpg"
      ],
      "tags": [
        {"id": 1, "name": "cute"},
        {"id": 2, "name": "playful"}
      ],
      "status": "available"
    },
    "schemaValidation": {
      "valid": true,
      "schema": "#/components/schemas/Pet"
    }
  },
  "success": true
}

Error Response with OpenAPI Error Schema

{
  "operationResponse": {
    "statusCode": 400,
    "headers": {
      "content-type": "application/json"
    },
    "data": {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid pet data provided",
        "details": [
          {
            "field": "name",
            "issue": "Name is required"
          },
          {
            "field": "category.id",
            "issue": "Category ID must be a positive integer"
          }
        ]
      }
    },
    "schemaValidation": {
      "valid": true,
      "schema": "#/components/schemas/Error"
    }
  },
  "success": false
}

Pagination Response Handling

{
  "operationResponse": {
    "statusCode": 200,
    "data": {
      "items": [
        {"id": 1, "name": "Pet 1"},
        {"id": 2, "name": "Pet 2"}
      ],
      "pagination": {
        "offset": 0,
        "limit": 20,
        "total": 156,
        "hasMore": true,
        "nextOffset": 20
      }
    },
    "links": {
      "self": "/pets?offset=0&limit=20",
      "next": "/pets?offset=20&limit=20",
      "last": "/pets?offset=140&limit=20"
    }
  },
  "success": true
}

Editor Features

OpenAPI Editor Capabilities:

Operation Browser: Navigate through all available API operations from specification
Parameter Auto-completion: Schema-based parameter suggestions and validation
Schema Explorer: Interactive exploration of OpenAPI data models
Response Examples: Example responses from OpenAPI specification
Security Assistant: Guided setup of authentication based on security schemes
Validation Helpers: Real-time parameter and schema validation

For complete editor details, see Code Editing & Schema Reference.

Specification Explorer

Interactive API Documentation

The OpenAPI editor includes a built-in API documentation browser that displays all operations, parameters, schemas, and examples directly from the specification.

Explorer Features:

Operation Catalog: Browse all API endpoints organized by tags
Schema Browser: Explore data models and their relationships
Example Gallery: View request/response examples from specification
Security Reference: See all available authentication methods
Server Information: View available servers and environments

Additional Features

Specification Composition

Combine multiple OpenAPI specifications:

{
  "compositions": [
    {
      "specificationUrl": "https://api.company.com/users/v1/openapi.json",
      "basePath": "/users"
    },
    {
      "specificationUrl": "https://api.company.com/orders/v2/openapi.json", 
      "basePath": "/orders"
    }
  ],
  "mergeStrategy": "prefix-operations"
}

Custom Headers and Middleware

Add custom headers to all requests:

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "globalHeaders": {
    "X-Client-Version": "axellero-2.1.0",
    "X-Request-ID": "{{ctx.nodes.idGenerator.outputs.requestId}}",
    "X-User-Context": "{{ctx.user.login}}",
    "X-Workspace": "{{ctx.workspace_slug}}"
  }
}

Response Transformation

Transform responses based on OpenAPI specification:

{
  "operationId": "listPets",
  "responseTransformation": {
    "enabled": true,
    "flattenArrays": false,
    "camelCaseKeys": true,
    "removeNullFields": true,
    "addMetadata": {
      "fetchedAt": "{{ctx.nodes.timer.outputs.currentTime}}",
      "fetchedBy": "{{ctx.user.id}}"
    }
  }
}

Error Handling

OpenAPI-specific Error Processing

{
  "operationId": "createOrder",
  "errorHandling": {
    "retryOn": [429, 502, 503, 504],
    "retryAttempts": 3,
    "retryDelay": 2000,
    "errorMapping": {
      "400": {
        "action": "validate_input",
        "message": "Invalid request data"
      },
      "401": {
        "action": "refresh_token",
        "message": "Authentication required"
      },
      "404": {
        "action": "create_resource",
        "message": "Resource not found"
      },
      "429": {
        "action": "rate_limit_wait",
        "message": "Rate limit exceeded"
      }
    }
  }
}

Schema Validation Errors

{
  "schemaValidationError": {
    "message": "Request validation failed",
    "errors": [
      {
        "keyword": "required",
        "dataPath": ".name",
        "schemaPath": "#/required",
        "params": {"missingProperty": "name"},
        "message": "should have required property 'name'"
      }
    ],
    "schema": "#/components/schemas/Pet",
    "specification": "https://petstore.swagger.io/v2/swagger.json"
  }
}

Performance Optimization

Specification Caching

Smart Caching

OpenAPI specifications are automatically cached and only refetched when the specification URL or version changes, improving performance for repeated operations.

{
  "specificationUrl": "https://api.example.com/openapi.json",
  "caching": {
    "enabled": true,
    "ttl": 3600,
    "refreshOnEtag": true,
    "refreshOnModified": true
  }
}

Operation Optimization

{
  "operationId": "bulkCreateItems",
  "optimization": {
    "batchSize": 100,
    "parallelRequests": 5,
    "connectionPooling": true,
    "compressionEnabled": true
  }
}

Getting Started

Obtain OpenAPI Specification: Get the OpenAPI/Swagger specification URL or file
Import Specification: Configure the OpenAPI node with the specification URL
Configure Authentication: Set up security based on specification security schemes
Explore Operations: Browse available operations using the built-in explorer
Execute Operations: Call API operations with automatic validation
Handle Responses: Process validated responses and handle errors appropriately
Test Integration: Validate the integration with sample data and edge cases

OpenAPI

Specification Import

Operation Discovery

Schema Validation

Security Configuration

On this page