Articles in this section

Generate an OpenAPI specification

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:

  1. Navigate to Resources → Exports.

–– OR ––

  1. Navigate to a flow and click your export.
  2. Scroll to Advanced.
  3. 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:

  1. Navigate to Resources → Imports.

–– OR ––

  1. Navigate to a flow and click your import.
  2. Scroll to Advanced.
  3. 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:

  1. Navigate to Resources → Exports.

–– OR ––

  1. Navigate to a flow and click on your listener.
  2. Scroll to Public URL.
  3. 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.
Was this article helpful?
1 out of 1 found this helpful

Comments

0 comments

Please sign in to leave a comment.