Using an OpenAPI Specification

To configure a flow with an API specification file, you can add a ReceiveHTTPMessage trigger to the flow and upload an API specification file.

When you implement a Spec, the ConfigureHTTPResponse and Return activities are automatically added to the flow. The mappings from trigger output to flow inputs get configured for you based on the definitions in the specification. The output of the ConfigureHTTPResponse activity is automatically mapped to the Return activity input. However, you must configure the input to the ConfigureHTTPResponse activity manually.

If you have multiple response codes configured in the REST trigger, the first response code is configured in the ConfigureHTTPResponse activity by default. However, if you have the 200 response code configured, then that is the default value in ConfigureHTTPResponse activity.

Considerations when using an API specification file to create a flow:

  • Swagger Specification 2.0 and OpenAPI Specification 3.0 are supported.
  • Currently, only the JSON format is supported.

  • API specification files with cyclic dependency are supported in ReceiveHTTPMessage trigger and InvokeRestService activity. Schema properties with cyclic dependency are converted into empty schema objects. For example, if you have a type Book that contains an object element of the type Author. The type Author contains an element of the type Book, which represents the books written by the author. To retrieve the Author, it creates a cyclic dependency where the Author object contains the Book object and the Book type contains the Author object. Here, the Author type is converted to an empty object to support cyclic schema rendering in the mapper.

  • String, integer, and boolean are the supported data types. A data type that appears in your specification but is not supported results in an error being displayed.
  • Schema references within schemas are not supported.
  • If the specification has a response code other than 200 (OK) or 500 (Error), the method that contains the unsupported response code is not created.
  • You can enter a schema for the response code 200, but the 500 response code must be a string.
  • Basepath element in the schema is not supported.
Note: The REST reply data type is by default set to any data type. To configure the reply to an explicit data type, see Configuring the REST Reply section.

To create an app using an API specification and upload the specification file:

    Procedure

  1. Create a New Flogo app.

  2. Open the created flow and drag the ReceiveHTTPMessage trigger to it.

  3. Set the Configure Using API Specs radio button to True.

  4. Browse for the API spec file. If the API spec file is valid, then the supported path and associated methods populate the dropdown menu.

  5. In the dropdown menu, select the path and method and finish the trigger configuration.

    You have added the ReceiveHTTPMessage trigger with parameter values, Request body, and Response body from the selected API specification file.

Note: Available data and flow inputs are auto-mapped in Map to Flow Inputs. Available data and trigger reply are auto-mapped in Map from Flow Outputs.

To implement flows in an app using an API specification, see Implementing Specs.

The supported Swagger 2.0 and OpenAPI Specification 3.0 features are given in the following list:

  • Path Templating

  • Media Type

    • Request Types: application/json, multipart/formdata, x-www-form-urlencoded

    • Response Types: text/plain, application/json

  • Multiple Status Codes

  • Path Item Object

  • Parameter Object

  • Request Body Object

  • Reference Object

  • Header Object

  • Security Scheme Object

  • allOf, oneOf, and anyOf keywords

For more information, refer to OpenAPI Specification.