You can now generate an OpenAPI Specification (spec) for any export, import, lookup, or the Celigo integrator.io listener.
The OpenAPI Spec is a standard format for describing REST APIs. It allows humans and computers to understand the capabilities of a service without accessing its source code or documentation. OpenAPI Specs define the endpoints, request parameters, response formats, authentication methods, and other details of a REST API. In integrator.io, the specs are written in YAML format.
It’s important to note that the OpenAPI Specs don’t include sensitive information. They simply use existing mock or preview data to collate the available fields in the API and package them in a simple file.
You can use the OpenAPI Specs for many things. The most common reason is to trigger exports, imports, and lookups from external applications and expose the endpoints to your customers. When you generate a spec, you’ll receive a .yaml or .yml file you can open with any text editor or notepad. From there, you can see all the fields available for your resource. Below is an example export for ReCharge. As you can see, you’re provided with the invoke URL, title, description, and version of the export.
openapi: 3.0.3
info:
title: ReCharge export
description: Test for OpenAPI Spec
version: 1.0.0
servers:
- url: -
https://api.integrator.io/v1/exports/65•••••••••••••be0/invoke
paths:
/:
post:
security:
- bearerAuth: []
description: Test for OpenAPI Spec
parameters: []
responses:
'200':
description: Response Object
content:
application/json:
schema:
$ref: '#/components/schemas/responseSchema'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/requestSchema'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
schemas:
responseSchema:
type: object
properties:
page_of_records:
type: array
items:
type: object
properties:
record:
type: object
properties:
address1:
type: string
address2:
nullable: true
cart_attributes:
nullable: true
cart_note:
nullable: true
city:
type: string
company:
nullable: true
country:
type: string
country_code:
type: string
created_at:
type: string
format: style
customer_id:
type: integer
discount_id:
nullable: true
first_name:
type: string
id:
type: integer
last_name:
type: string
note_attributes:
nullable: true
original_shipping_lines:
nullable: true
phone:
type: string
format: color
presentment_currency:
type: string
province:
type: string
shipping_lines_override:
nullable: true
updated_at:
type: string
format: style
zip:
type: string
format: utc-millisec
requestSchema:
type: object
properties:
data:
type: object
properties:
export:
type: object
properties:
http:
type: object
properties:
paging:
type: object
properties:
page:
type: string
OpenAPI Specs can be downloaded for exports, imports, lookups, and integrator.io webhook listeners regardless of whether they’re used in a flow. Your connection does not have to be online to generate an OpenAPI Spec.
Important
You must create and save the export, import, lookup, or listener before generating a specification.
The request schema is generated using the export or lookup configuration. The schema considers almost all configurable fields, including custom settings, handlebars, and dates. The only fields that are not considered are those that are included in scripts.
The response schema is generated using the mock output data or is received from the preview endpoint data. Note that the connection must be online for this to work. The spec will consider filters, transformations, and hooks associated with the export or lookup. The response schema will be empty if the mock output is empty and the preview call fails.
Warning
If you try downloading a spec without mock data or a failed endpoint preview, you’ll receive a warning message telling you to update the mock output for an improved YAML.
To generate an OpenAPI Spec for an export or lookup:
-
Navigate to → .
–– OR ––
Navigate to a flow and click your export.
-
Scroll to Advanced.
-
Click the Download OpenAPI spec link.
The link will download the specs to your system.
The OpenAPI Spec request schema is generated using the import configuration. The schema considers almost all configurable fields, including handlebars and custom settings. The only fields that are not considered are those that are included in scripts.
Unless mappings are available, the request schema is based on the HTTP request body. If mappings are available, the spec request schema will be based on that. If only mock input data is available, the spec request will be based on that. The request schema will be based on the source record if none of the above are available. If the source record isn’t available, the spec will be generated with an empty request body.
The OpenAPI Spec response schema is based on the mock response data. If that data isn’t available, it will generate the default response structure.
To generate an OpenAPI Spec for an import:
-
Navigate to → .
–– OR ––
Navigate to a flow and click your import.
-
Scroll to Advanced.
-
Click the Download OpenAPI spec link.
The link will download the specs to your system.
Important
OpenAPI specs are only available for the Celigo integrator.io webhook listener. They are not available for other webhooks.
The OpenAPI Spec request schema will be based on the mock output or sample data. If both are available, the request will be based on the sample data. A standard schema with limited information, empty data objects, and error objects with codes and messages will be provided if both are unavailable.
If the Override HTTP response body for success responses field is populated, the response schema will be based on the information provided. If not, the response schema will be empty. If the Override HTTP status code for the success responses or Override media type for success responses fields are configured, the response schema will be based on that information.
To generate an OpenAPI Spec for a listener:
-
Navigate to → .
–– OR ––
Navigate to a flow and click on your listener.
-
Scroll to Public URL.
-
Click the Download OpenAPI spec link.
The link will download the specs to your system.
The following warnings may appear based on your provided data.
-
If the mock output isn’t available, you’ll get an error stating, “The mock output is not present. Provide mock output data for exports and lookups for an improved OpenAPI YAML file.”
-
If the mock response isn’t available, you’ll get an error stating, “The mock output is not present. Provide mock output data for exports and lookups for an improved OpenAPI YAML file.
-
If the request body and mappings aren’t available, you’ll get an error stating, “The request body and mappings are not present. Update the import request body and flow mappings for an improved OpenAPI YAML file.”
-
If the mock response, request body, and mappings aren’t available, you’ll get an error stating, “The mock response, request body, or flow mappings are not present. Update either the mock response, mappings, or request body for an improved open OpenAPI YAML file.”
-
If the sample data or mock output data aren’t available, you’ll get an error stating, “Update sample data or mock output for an improved OpenAPI YAML file.”
-
If the OpenAPI Spec cannot be generated due to
-
Backend error – “Not able to generate the OpenAPI spec; try again later.”
-
Unknown error – “Not able to generate the OpenAPI spec; contact Celigo support.”
-