Export OpenAPI Definitions

If you're building Workflows that will be consumed as APIs, it's often useful to be able to export formal definitions of the Workflows.

From the Workflows view, select one or more Workflows, open the download menu, then click Download OpenAPI definition.

In the export dialog, choose the Environment and OpenAPI version to generate.

The generated definition can also be downloaded directly from the Environment hostname at GET https://{environment-hostname}/openapi.yml.

You'll be able to use services like Swagger Hub to test APIs as well as generate code stubs to consume these APIs.

Additionally, the REST Request Node supports these definitions.

Tips for creating rich definitions

Follow these tips to ensure that the generated definitions are as rich as possible.

Provide a description for each Workflow in the Workflow Design Settings Pane - this will be used as the service description.

For current V2 HTTP-bound Workflows, the OpenAPI definition is generated from the published HTTP trigger and HTTP respond steps. Apply these tips:

• Configure the HTTP method and route on the trigger step.
• Provide representative request body and request header definitions on the HTTP trigger step when the Workflow accepts input.
• Add an HTTP respond step and configure its status code, body and headers if you want the OpenAPI response contract to be explicit. Without published HTTP respond metadata, the generated definition falls back to a 200 response without a body.

For legacy V1 HTTP-bound Workflows that use Variable Bar properties to define the interface, keep those properties strongly typed and documented:

• Set the data type correctly instead of leaving everything as Text.
• Use Notes to describe Properties.
• If you're using the payload Properties FgRequestBody and FgResponseBody, ensure they contain sample values, especially for JSON or XML.
• If you're using header Properties FgRequestHeaders and FgResponseHeaders, ensure they contain sample values.