When working with AWS API Gateway, it uses a number of features that are a step away from the OpenAPI standard.

Usefully, the features are documented here AWS API Gateway Important Notes, but it's very easy for API developers to forget, or miss them.

This linter is designed to support only the OpenAPI v3 specificiation on AWS API Gateway. AWS' documentation is not particularly clear on the differences between the two implementations, but as historical documentation gets updated this library will hopefully become more accurate and relevant to v3. If you're using V2, please note that this linter is likely to provide you false-positive, and false-negative results.

Spectral is an Open Source API Linter.

Spectral is an open source JSON/YAML linter, which allows you to create style guides for your structured data; things like OpenAPI/AsyncAPI/RAML descriptions, Kubernetes config, GitHub Actions, you name it, Spectral can help you lint it. Go beyond making sure they are “Technically Correct”, make sure they are useful.

Try it out:

If you've got npx installed, then you can run this ruleset with a single command, replacing $your_api.yml - with your API definition:

npx spectral lint -r https://raw.githubusercontent.com/andylockran/spectral-aws-apigateway-ruleset/main/aws_important_notes.yml $your_api.yaml

To use this ruleset, simply extend your .spectral.yml ruleset by adding a reference to this ruleset, eg:

extends:
  - spectral:oas
  - spectral-aws-apigateway-ruleset

This pulls the definition directly from npm, so you don't have to even install it!

spectral-aws-apigateway-ruleset

See: Spectral Instructions for npm for more details.

The severity of each of these rules has been tweaked to follow my own usage. If you think the severity needs changing, or would prefer a more descriptive error message, please submit a PR.

For instructions on how to do so, refer to Custom Rulesets on the Spectral site.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.