Disclaimer: This tutorial assumes you have an existing AWS API Gateway with an API configured. It also assumes you have the latest version of the AWS CLI installed on your machine.
If you’re here, you likely already know what OpenAPI Spec, formerly Swagger, is and you’re trying to determine how do I export an OpenAPI Spec from AWS API Gateway? If so, I encourage you to take note of your API type (HTTP or REST) and skip to the relevant section below.
If you are not familiar with OpenAPI Spec, please read the next section.
The OpenAPI Specification, also known as Swagger Specification, is a widely used open standard for defining and documenting RESTful APIs. The OpenAPI Specification provides a structured way of defining endpoints, request parameters, response formats, security mechanisms, and other details about a RESTful API. It allows developers to quickly understand and integrate with an API, and simplifies the process of building API clients and documentation.
Knowing how to export an OpenAPI specification from a RESTful API is essential for efficient communication and onboarding of users and new developers. By exporting an OpenAPI spec, developers can easily share the structure and functionality of their API with others, including documentation, client libraries, and server stubs. This helps users and new developers quickly understand the API and how to interact with it, reducing the time and effort required for onboarding. Additionally, the OpenAPI spec promotes consistency and interoperability across different API implementations, making it easier to integrate with other systems and services.
Below is an example of how to export both the YAML and JSON format for an HTTP type API from AWS API Gateway. Replace the api-id and stage-name parameters with your details.
# YAML export to a file called stage-definition.yaml aws apigatewayv2 export-api \ --api-id gwsmxnlmff \ --output-type YAML \ --specification OAS30 \ --stage-name astage \ stage-definition.yaml # JSON export to a file called stage-definition.json aws apigatewayv2 export-api \ --api-id gwsmxnlmff \ --output-type JSON \ --specification OAS30 \ --stage-name astage \ stage-definition.json
Below is an example of how to export both the JSON format for a REST type API from AWS API Gateway. Replace the rest-api-id and stage-name parameters with your details.
# JSON export to a file called stage-definition.json aws apigateway get-export --parameters extensions='apigateway' \ --rest-api-id gwsmxnlmff \ --stage-name astage \ --export-type swagger \ stage-definition.json