terraformaws-api-gatewayopenapi

Deploying an OpenAPI-based API gateway via Terraform?

I was given a link to an OpenAPI 3.0.1 definition hosted on SwaggerHub, and was told to deploy it. On the Terraform side, I see way too many resources that confuse me, I'm not sure which one to use. What's the most straightforward way to deploy an API gateway via Terraform that's already all configured in an OpenAPI definition? Is there a resource that would simply let me provide an OpenAPI definition URL to the API gateway, or would I have to copy paste the actual JSON somewhere?

Solution

  • The AWS API Gateway service has two main usage patterns:

    1. Directly specify individual resources, methods, requests, integrations, and responses as individual objects in the API Gateway API.
    2. Submit an OpenAPI definition of the entire API as a single unit and have API Gateway itself split that out into all of the separate objects in API Gateway's data model.

    Since the underlying API supports both models, it can be hard to see initially which parts are relevant to each usage pattern. The Terraform provider for AWS follows the underlying API design, and so that confusion appears there too.

    It sounds like you are intending to take the second path I described above, in which case the definition in Terraform is comparatively straightforward, and in particular it typically involves only a single Terraform resource to define the API itself. (You may need to use others to "deploy" the API, etc, but that seems outside of the scope of your current question.)

    The api_gateway_rest_api resource type is the root resource type for defining an API Gateway REST API, and for the OpenAPI approach is the only one required to define your entire API surface, by specifying the OpenAPI definition in its body argument:

    resource "aws_api_gateway_rest_api" "example" {
  name = "example"
  body = file("${path.module}/openapi.json")
}

    In the above example I've assumed that you've saved the API definition in JSON format in an openapi.json file in the same directory as the .tf file which would contain the resource configuration. I'm not familiar with SwaggerHub, but if there is a Terraform provider available for it which has a data source for retrieving the definition directly from that system then you could potentially combine those, but the principle would be the same; it would only be the exact expression for the body argument that would change.

    The other approach with the resources/etc defined explicitly via the API Gateway API would have a separate resource for each of API Gateway's separate object types describing an API, which makes for a much more complicated Terraform configuration. However, none of those need be used (and indeed, none should be used, to avoid conflicts) when you have defined your API using an OpenAPI specification.

    NOTE: The above is about API Gateway REST APIs, which is a separate offering from "API Gateway v2", which offers so-called "HTTP APIs" and "WebSocket APIs". As far as I know, API Gateway v2 doesn't support OpenAPI definitions and therefore I've assumed you're asking about the original API Gateway, and thus "REST APIs".