Using an Open API Specification (Swagger)

TIBCO Cloud Integration - Flogo (PAYG) gives you the option to create the Flogo app logic (flows) by importing a Swagger 2.0 specification file. You simply drag and drop a Swagger file into the TIBCO Cloud Integration - Flogo (PAYG) UI or navigate to it, or if you already have a Swagger specification stored in the TIBCO Cloud™ Integration - API Modeler select it when creating the flow and the flows for your app automatically get created based on the definitions in the Swagger file that you uploaded.

Before the TIBCO Flogo® App is created, a validation process takes place to ensure that the features defined in the Swagger specification are supported by TIBCO Cloud Integration - Flogo (PAYG). So, consider the following when using a Swagger specification to create a TIBCO Flogo® App:

  • TIBCO Cloud Integration - Flogo (PAYG) supports Swagger 2.0.
  • Currently, TIBCO Cloud Integration - Flogo (PAYG) supports only the JSON format.
  • Cyclic dependency is not supported while creating flows from Swagger specifications. For example, if you have a type Book which 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 retreive 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 TIBCO Cloud Integration - Flogo (PAYG). A data type that appears in your specification but is not supported in TIBCO Cloud Integration - Flogo (PAYG) will result in an error being displayed.
  • Schema references within schemas are not supported
  • If the specification has a response code other than 200 (OK) and 500 (Error), the method that contains the unsupported response code will not be 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

Should you get a validation error, you will have the option to either cancel out of the process of generating the app or you can click Continue. If you opt to continue, TIBCO Cloud Integration - Flogo (PAYG) will continue with the app creation and ignore the parts of the specification that did not pass the validation due to which you got an error.

Note: The REST reply data type is by default set to data type any. To configure the reply to an explicit data type, see Configuring the REST Reply section.

To create an app using a Swagger specification, follow these steps:

To upload your Swagger file, follow these steps:

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 to TIBCO Cloud™ Integration - Flogo® (PAYG). 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.
    TIBCO Cloud Integration - Flogo (PAYG) validates your file extension. If your file extension is .json, you see a green check mark and the Upload button appears.
    TIBCO Cloud Integration - Flogo (PAYG) 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 parameterised 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

    TIBCO 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 Swagger 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. To do so, follow 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.

    Click the Publish to Mashery link to publish your specification to TIBCO Cloud™ Mashery®.

Related tasks