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.

You can work with the exported OpenAPI document in the following ways.

You can import the document 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. You can then publish the API (to a product in a catalog) and socialize it.
You can share the API definition with other users.
You can add the document as an imported API in App Connect Designer from the Applications and APIs page. For more information, see How to use IBM App Connect with APIs imported from OpenAPI documents.
You can add the OpenAPI document 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 dashboard , locate the API flow, open its menu, 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.
  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 get a compressed file that contains the OpenAPI document and a BAR file.
- 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, save the file, which is named after your flow by default, as flowName-openapi.yaml or flowName-openapi.json.
Depending on your browser, the file might 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.
- If the conditions for unified authoring are met in both App Connect Designer and API Connect, the exported OpenAPI document includes some extensions that apply to API Connect. The first extension is an x-ibm-name setting in the info section. The other extension is an x-ibm-configuration section with the policy definition that is configured in the Policies view of the Gateway tab in your Designer instance.
  (You can use the unified authoring feature to simultaneously expose your API in both App Connect Designer and API Connect, as described in 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 in a servers section of the exported OpenAPI document. If the conditions for unified 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 that are in a Stopped state.
Tip: While you are testing a running flow, you can also download the OpenAPI document, which describes the API. Go to the Test tab and find the download link on the Overview page. For more information, see Testing flows during development.