Exporting your API flow as an OpenAPI document

From App Connect Designer, you can export your API flow as an OpenAPI document that defines all the resources and operations of the REST API.

About this task

When you export the API definition, you can choose a YAML or JSON format that conforms either to the OpenAPI Specification Version 2.0 or OpenAPI Specification Version 3.0.

Some ways in which you can work with the exported OpenAPI document are as follows:

You can import it into an API management tool or a REST client of your choice. For example, you can import the OpenAPI document into IBM® API Connect to further develop and test the API, which can subsequently be published (to a Product in a Catalog) and socialized.
You can share the API definition with other users.
You can add it as an imported API to an App Connect Designer instance from the Catalog > APIs tab. For more information about adding an OpenAPI document as an imported API, see How to use IBM App Connect with APIs imported from OpenAPI documents.
You can add it to a source control system for backup purposes.

Procedure

To export a flow as an OpenAPI document, complete the following steps:

From the App Connect Designer UI, click the Dashboard icon to open the App Connect Designer dashboard (if not currently on display).
Locate the API flow, open its menu, and then click Export. The flow can be in a Stopped or Running state.
From the Export panel, choose your preferred syntax for the OpenAPI document:
- Click OpenAPI V3.0 (YAML) to export the flow in a YAML format that conforms to the OpenAPI Specification Version 3.0. (YAML is generally considered easier to read and construct, and provides support for extra features such as comments.)
  Tip: You can also use the OpenAPI V3 YAML and Runtime flow BAR assets (ZIP) option to export the flow in a YAML format that conforms to the OpenAPI Specification Version 3.0. With this option, you will obtain a ZIP archive that contains the OpenAPI document as well as a BAR file that can be deployed into an App Connect Dashboard instance as an integration server or integration runtime. For more information about exporting and deploying a BAR file to an integration server or integration runtime, see Export guidelines and Deploying Designer and Toolkit integrations in the App Connect Dashboard.
- Click OpenAPI V3.0 (JSON) to export the flow in a JSON format that conforms to the OpenAPI Specification Version 3.0.
- Click OpenAPI V2.0/Swagger document (YAML) to export the flow in a YAML format that conforms to the OpenAPI Specification Version 2.0.
- Click OpenAPI V2.0/Swagger document (JSON) to export the flow in a JSON format that conforms to the OpenAPI Specification Version 2.0.
Click Export.
If prompted, choose to save the file, which is named after your flow by default, as flowName-openapi.yaml or flowName-openapi.json; for example, Customer API-openapi.yaml or Customer API-openapi.json.
Depending on your browser, the file might also be automatically downloaded to a configured download location.
Note: If you chose to export in a YAML or JSON format that conforms to the OpenAPI Specification Version 3.0, the following results apply:
- Applicable to IBM Cloud Pak for Integration only: If the conditions for the co-authoring feature are satisfied in both App Connect Designer and API Connect, the exported OpenAPI document will include the following extensions, which are applicable to API Connect:
  - An x-ibm-name setting in the info section
  - An x-ibm-configuration section with the policy definition that is configured in the Policies view within the Gateway tab in your Designer instance
  (The co-authoring feature enables you to simultaneously expose your API in both App Connect Designer and API Connect, as described in IBM Cloud Pak for Integration only: Creating flows for an API from scratch.)
- If you exported a flow in a Running state, the endpoint URL of the running API is included within a servers section in the exported OpenAPI document. If the conditions for the co-authoring feature are satisfied, the API endpoint is provided by the Gateway service in API Connect; otherwise, this endpoint is provided by App Connect Designer.
  The servers section is omitted for flows in a Stopped state.
Tip: While testing a running flow, you can also download the OpenAPI document, which describes the API, from the Overview page on the Test tab. For more information, see Testing a running API flow.