Skip to main content
In this guide, we demonstrate how to integrate OpenAPI with API Gateway. API Gateway offers two key features:
  1. You can generate an OpenAPI specification from an existing API configured in API Gateway.
  2. You can import a pre-existing OpenAPI specification to automatically create a new REST API in API Gateway.
Follow this step-by-step walkthrough to learn how to export, modify, and import API configurations seamlessly.

​
Generating an OpenAPI Specification from an Existing API

If you already have an API configured in API Gateway, you can generate an OpenAPI specification from it. Start by navigating to the API’s stage (for example, the “dev” stage).
The image shows an AWS API Gateway console with details of a stage named "dev" for an API called "taskmanager." It includes information about the stage's settings, invoke URL, and logging options.
Next, select the stage actions and choose Export. In the export dialog, pick the API specification format you prefer. You can select either Swagger or OpenAPI 3, available in JSON or YAML. Additionally, you can include API Gateway or Postman extensions if needed.
The image shows an "Export API" dialog box from AWS API Gateway, where options for API specification type, format, and extensions are being selected. The user can choose between Swagger and Open API 3, JSON or YAML format, and different extension options before exporting the API.
After choosing the appropriate options, click Export API. The OpenAPI spec file will then be downloaded. When you open this file in a text editor, you might see a structure similar to the snippet below:
You can modify the specification as required. For example, to rename the API title to “taskmanager2”, update the spec as follows:
Make sure to save your changes after modifying the OpenAPI specification.

​
Importing an OpenAPI Specification into API Gateway

To create a new API in API Gateway using your updated specification, import the OpenAPI file. This feature is particularly useful when you want to convert an existing API from another platform into an API Gateway configuration. When you import the OpenAPI spec, API Gateway reads the file and automatically creates the API resources and methods. The configuration might resemble the example below:
Click Create API to finish the process. Once created, you’ll see an API named “taskmanager2” with the specified configuration. Although the import provides the foundational setup, some integrations might require additional manual configuration.
The image shows an AWS API Gateway interface with a POST method for a "/tasks" resource, indicating an undefined integration warning.
After the import, review and update the configurations to ensure everything is set up correctly.
The image shows the AWS API Gateway console, displaying the configuration of a REST API named "taskmanager2" with resources and methods like GET and POST under the "/tasks" path.
Pay close attention to integration settings. Some configurations imported from other platforms might need manual adjustments in API Gateway.

​
Generating an SDK

In addition to managing API configurations, API Gateway allows you to generate an SDK for your APIs. To generate an SDK for the API (for example, taskmanager), return to the stages section in API Gateway and follow the instructions to produce an SDK. This SDK helps your clients quickly integrate with your API on their desired platforms.
In summary, this guide explained how to:
  • Generate an OpenAPI specification from an existing API.
  • Modify the specification for your own requirements.
  • Import the modified specification to create a new API in API Gateway.
  • Optionally generate an SDK for enhanced client integration.
We hope you find this tutorial useful. Happy coding!

Watch Video