OpenAPIv3 as the source of truth

OpenAPIv3 can be leveraged as a single source of truth when building AWS REST API Gateways. Terraform configuration can pull it in, and AWS vendor extensions ensure that API Gateway integrations are stood up.

OpenAPIv3 as the source of truth in an AWS API Gateway

The Problem

Perhaps you’ve stood up a REST API in AWS before. Perhaps you are aware of OpenAPIv3 spec and have used the AWS Console to stand up a REST API Gateway from this specification file.

Perhaps you’ve also worked with GraphQL and found OpenAPIv3 spec, at first glance, did almost what you needed in AWS API Gateway, but fell short of the mark of integrations and connecting Lambdas and Mocks to your gateway.

REST assured, OpenAPIv3 can be leveraged as a single source of truth when building AWS REST API Gateways. Terraform configuration can pull it in, and AWS vendor extensions ensure that API Gateway integrations are stood up.

The Solution

The solution to the question you’ve likely had, that I had, comes in the form of vendor extensions within the OASv3 spec file.

What are Vendor Extensions?

Vendor extensions describe extra functionality that is not covered by the standard OpenAPI Specification, and are custom properties within the OASv3 spec that start with x-.

From the Swagger vendor extension page, a sample YAML-based AWS API Gateway vendor extension describing that an endpoint will take an API Key in the header, integrates with a Lambda authorizer function, and is secured via OAuth2, follows below:

components:
  securitySchemes:
    APIGatewayAuthorizer:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: oauth2
      x-amazon-apigateway-authorizer:
        type: token
        authorizerUri: arn:aws:apigateway:us-east-1:lambda:path/2015-03-31/functions/arn:aws:lambda:us-east-1:account-id:function:function-name/invocations
        authorizerCredentials: arn:aws:iam::account-id:role
        identityValidationExpression: "^x-[a-z]+"
        authorizerResultTtlInSeconds: 60

AWS API Gateway Vendor Extensions

A list of AWS API Gateway vendor extensions is found within AWS’s API Gateway developer guide documentation page.

An Extended Solution–Generating Documentation

With a complete OpenAPIv3 spec in hand, from which infrastructure is built and connected, you have a great resource for documentation.

There are more than a few OASv3-to-documentation products, but I prefer redocly if I don’t need interactivity, and Swagger UI if I want to potentially expose the ability for a consumer to make test calls against the API.

With either solution, as your code repo will most likely be hosted on either GitLab or GitHub, I find it useful to make a Pages site from the code repo and attach a pages job. I’ve had good luck with pulling in swagger-ui-dist, copying the spec from its code directory to /public/, and injecting values into swagger-initializer.js from the pages job to render the OASv3 spec.

Summary

When considering standing up an AWS API Gateway, especially when standing it up using an IaC solution (e.g. Terraform, SAM, SLS, CloudFormation), it is not only possible to integrate with AWS API Gateway through an annotated OASv3 spec file, but also carry this file into an IaC solution for deployment of an API Gateway, and for subsequent documentation of the deployed artifact.

This approach removes the potential for as-imagined vs as-built drift, as the documentation is created from the same specification that is driving the deployment.