Skip to main content
Skip table of contents

How to expose your flow as an OpenAPI

STANDARD PREMIUM ULTIMATE

Include OpenAPI documentation for your http endpoints in your flow and automatically generate an API reference for easy access.

API Reference

Open the Flow App with the Flow Editor.

The Flow App provides an API Reference tab in the right sidebar.

default API Reference

A new Flow App without endpoint documentation will have an empty API reference with only a default name and version.

Clicking the Config button will open the Config section to update the main parameters and settings of the API Reference.

The API Reference button will open this sidebar in a new tab. This address can be used to share a standalone Reference of your API.

The path /http-api/openapi.json is the path to the OpenAPI spec object that contains all the raw information once they have been configured.

Config

The config tab can be used to update the descriptive information of your API, as well as global settings.

The main section contains:

Name

Required

Description

Title

true

Title of the API Reference

Version

true

Version of the API Reference

Description

false

Optional description for the overall API functionality

Security

false

global security scheme to protect every endpoint

As example, this could be some of the values. The security selection will be empty at first. Schemes can be added with the Edit button. Further information in the security section.

Config example

The Advanced section offers more information that can be provided for the API Reference:

Advanced settings

Adding an operation

To add a new endpoint documentation and fill in the API Reference with operations, you need to configure an http node.

A new Endpoint can be created by adding an http in node. The node needs to be configured with a method and URL path.

Http node

Endpoint config

Click Add to add a new documentation for the endpoint. The documentation page will offer an Info tab with some optional parameters:

Endpoint info

Name

Description

Summary

short description of the endpoint

Description

longer description of the endpoint

Tags

comma separated list of tags or categories this endpoint belongs to

Consumes

Mime type of the incoming request

Produces

Mime type of the outgoing response the flow connected to this endpoint is supposed to produce

Security

security scheme specific to this individual endpoint

Deprecated

mark the endpoint as deprecated

The Parameters tab offers the definition of parameters to be expected on a request to the endpoint. Parameters can be added with the + parameter button. A parameter can be added in query, header, formData or body.

Each parameter can be defined with a name and description. They can have different properties with types and formats (formats can often be any string). The type Array has preset format options and will provide defining elements as part of that array

The body parameter can be set up with multiple properties.

Each parameter can be marked as required, if your app always expects them.

Endpoint parameters

The response can be used to define multiple server responses from your endpoint. You can choose a Default response, or define status codes.

You can define multiple properties, just like for the request body parameter. Those properties will form the response object.

Endpoint repsonses

Path parameters

Path parameters can be included in the URL path with, for example, /user/:name. Name can be any parameter and is accessible at msg.req.params.

To register the path parameter with the API Reference, deploy your project after setting the URL path, to update the API Reference. After that, the path parameter will appear in the parameters section of the endpoint documentation.

Path parameter

Security options

Security schemes can be defined and added to both the Reference config and to each endpoint you describe. You can add a name and description to each security scheme.

The supported authorization types are: basic, API key and OAuth2.

Security config

API Key

API Key offers two versions to provide the key, in the header or as query parameter.

Both have to be defined with a custom parameter name.

OAuth2

OAuth2 offers four different methods: Implicit, Password, Application and Access Code.

All of them can be configured with scopes as comma separated list of scope names.

Based on the method, additional URL addresses of an authorization server are required.

Generated OpenAPI Reference

With endpoints and documentation added similar to the examples described here, deploying your changes will update the API Reference tab and you should see your operation.

Example API

The operation contains all the information defined in the endpoint documentation. It allows you to run a request on the server by clicking the Try it out button and providing all necessary parameters.

Example operation

The Authorize button or the lock icon on each endpoint opens a new window to add some credentials for your requests.

Example auth

As mentioned at the start, this API Reference can be opened in a separate window at /openapi-ui/index.html with the OpenAPI specification at /http-api/openapi.json.

These pages will be publicly available to help users interact with your app.

Limitations

  • body parameters and response objects cannot be set up with nested objects

  • body parameter and response object structures cannot be globally defined and reused across multiple operations

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.