Create An OpenAPI Spec from AWS API Gateway

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.

• Note to the Reader
• What is the OpenAPI Spec?
• Export HTTP API Spec
• Export REST API Spec

A Note to the Reader

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.

What is the OpenAPI Spec?

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.

Export HTTP API Spec

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

Export REST API Spec

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