How to expose your flow as an OpenAPI
STANDARD PREMIUM ULTIMATE
Add OpenAPI documentation to endpoints in your flow and expose an API reference.
More information about OpenAPI: OpenAPI Introduction
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