This is the latest Public Style Guides template available now in Stoplight Platform and in our open-source linting tool, Spectral. Sign up below to get notified of new templates, or log into your Workspace to try them out.
One of the primary reasons for creating OpenAPI documents is using 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.
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
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.
Quick Start with Stoplight Platform:
Stoplight Platform comes with a public style guides 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:
- Go to your Stoplight workspace.
- Create a style guide project OR edit a project that has an API.
- Select Manage Style Guides.
AWS API Gatewayfrom a list of public style guides.