Work Better with AWS API Gateway using Spectral

One of the primary reasons for creating OpenAPI documents is to use them in downstream tooling to automate tasks and streamline API development. OpenAPI documents are used to generate code, documentation, test cases, and SDKs, and deploy APIs to gateways. While OpenAPI support in these downstream tools is getting better, limitations exist that can lead to unexpected results.

AWS API Gateway is a popular API gateway used by numerous organizations to publish APIs. OpenAPI is one of the primary mechanisms used to manage and deploy these APIs, but AWS gateway, like many other tools, has limitations in terms of OpenAPI support. Some examples of these limitations are:

• Model names can only contain alphanumeric characters.
• Lack of support for OpenAPI keywords like discriminator, deprecated and exclusive minimum
• OpenAPI 3.1 is not supported

The full list of limitations is mentioned here.

While these limitations are listed in the documentation, it is easy for API designers and developers to miss resulting in unexpected results when deploying these APIs to the gateway.

Based on the work by Andy Lockran here, Stoplight Platform now has a Public Style guide to avoid some of these problems. Let’s take a quick tour through some of these rules to see how Spectral can keep all your API teams on track before they deploy their APIs on AWS API Gateway.

OpenAPI Versions

AWS API Gateway only supports OAS 3.0.1, so you can use this rule to enforce the use of only this version while APIs are being designed.

Missing Keyword Support

Keywords like default , exclusiveMinimum , exclusiveMaximum , readonly are not supported, so avoiding them will help keep consumers on the right track.

Naming and Patterns

Model names and path parameters can be in a particular format to be accepted by the AWS gateway. Using rules for this helps avoid invalid names and paths.

Here’s the full list of rules. Do you think we should add rules for something else? Leave your feedback here.

Quick Start with Stoplight Platform:

Stoplight Platform comes with a public style guide set that can be enabled within your Stoplight workspace with a single click. The AWS API Gateway Style Guide is the latest addition to the list.

To use these rules:

1. Go to your Stoplight workspace.
2. Create a style guide project OR edit a project that has an API.
3. Select Manage Style Guides.
4. Enable AWS API Gateway from a list of public style guides.