You can now generate an OpenAPI Specification (Spec) for any export, import, lookup, or listener.
OpenAPI Spec overview
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.
Using OpenAPI Specs
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
Generate an OpenAPI Spec
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.
Exports and lookups
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 Resources → Exports.
–– 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.
Imports
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 Resources → Imports.
–– 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.
integrator.io webhook listener
Important: OpenAPI specs are only available for the 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 Resources → Exports.
–– 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.
Errors and warnings
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.”
Comments
Please sign in to leave a comment.