Work Better with AWS API Gateway using Spectral

Nauman Ali
by Nauman Ali on December 1, 2022 3 min read

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.

Screenshot 2022-12-02 at 2.18.31 AM

Share this post

Stoplight to Join SmartBear!

As a part of SmartBear, we are excited to offer a world-class API solution for all developers' needs.

Learn More
The blog CTA goes here! If you don't need a CTA, make sure you turn the "Show CTA Module" option off.

Take a listen to The API Intersection.

Hear from industry experts about how to use APIs and save time, save money, and grow your business.

Listen Now