Using an OpenAPI Specification

Flogo Enterprise gives you an option to create the Flogo app logic (flows) by importing an API specification file. You can simply drag a specification file to the Flogo Enterprise UI or navigate to it. If you have an existing specification file stored in the TIBCO Cloud™ Integration - API Modeler, select it when creating the flow. The flows for your app are automatically created based on the definitions in the specification file that you uploaded.

When you create an app from a specification, the ConfigureHTTPResponse and Return activities are automatically added in 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. The only exception to this is if you have a response code of 200 configured. In that case, the 200 response code is configured in the ConfigureHTTPResponse activity by default.

Before the Flogo app is created, a validation process ensures that the features defined in the specification are supported in Flogo Enterprise.

Considerations when using an API specification file to create a Flogo app:

  • Flogo Enterprise supports Swagger Specification 2.0 and OpenAPI Specification 3.0.
  • Currently, Flogo Enterprise supports only the JSON format.
  • Cyclic dependency is not supported when creating flows from specifications. For example, if you have a type Book that contains an object element of type, Author. The type Author in turn contains an element of 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 in turn contains the Author object.
  • Not all data types are supported in Flogo Enterprise. A data type that appears in your specification but is not supported in Flogo Enterprise 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 are 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.

If you get a validation error, you can either cancel the process of generating the app or click Continue. If you opt to continue, the process of app creation continues and the parts of the specification that did not pass the validation are ignored.

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. Open the app details page and click Create.
    The Add triggers and flows dialog opens.
  2. Click Swagger Specification under Start with.
  3. You have two options:
    Create a flow using an API specification that exists in TIBCO Cloud™ Integration-API Modeler. In the API Specs tab, select the specification that you want to use.
    Use an API specification saved locally on your computer by uploading it toFlogo Enterprise. Click Upload file to open the tab. Browse to the saved API specification on your local machine or drag and drop your saved API specification to the Add triggers and flows dialog.
    Flogo Enterprise validates your file extension. If your file extension is .json, you see a green check mark and the Upload button appears.

    Flogo Enterprise validates the contents of your file and if it passes the validation, it creates the flows based on the definitions in the file. One flow gets created for each method and path combination defined in the file. If there are errors in your file, you get warning messages saying so, but you have the option to continue with creating the flows. If you click Continue, the flows get created for supported methods only. Other issues must be fixed before you can upload the file again.

    Note: Currently, the following are not supported:
    • PATCH method
    • Form data content type
    • Same root having a static path and a parameterized path in the file, for example, /foo/bar and /foo/{id}. But having two static paths are supported, for example, /foo/bar and /foo/bar1

    The Flogo app gets created and the flow details page opens with the flows created. Each flow corresponds to a method defined in the specification that passed the validation. These flows are automatically created based on the specification that you used to create the app. The flows are created with a REST trigger (ReceiveHTTPMessage) and have a REST Return activity appended to them by default.

  4. In each flow, do the following:
    1. Open the flow by clicking on its name.
    2. Click the trigger to open its configuration dialog.
    3. Map the following:
      • In the Map to Flow Inputs tab, map the Trigger Output to Flow Input.
      • In the Map from Flow Outputs tab, map the Flow Output to Trigger Reply.

    To test the deployed app, follow the procedure in Testing the Deployed App section.

    You can also download the specification used to create the app by following the procedure in Downloading the API Specification Used section.

    You also have the option to copy the Endpoint URL from the Endpoints tab by clicking Copy spec URL. Or you can click the () icon next to the Endpoint URL itself.