Best practice for integrating OpenAPI spec with Serverless

Hi all,

I’ve been doing some research to see if Serverless Framework is the best approach for my team vs rolling our own tooling and integrating with APIG directly. It seems like there are pros and cons (like anything).

One issue that seems to be up in the air is OpenAPI spec integration. The community seems to agree that it makes sense to define the API spec along with schemas and validation in one location and keep that one spec up-to-date. OpenAPI spec seems to be becoming the de-facto standard for describing APIs and is getting wider support from AWS. As interfaces generally last longer than their implementations I’m sure we should be describing our APIs with OpenAPI spec.

I’ve come across this GitHub issue ( which outlines an approach of using some Serverless plugins to allow documenting the Gateway with swagger and making use of validators / schemas.

Can anyone offer any further advice or point me to any reference documentation on best practice?

Essentially I want to be able to describe my APIs with OpenAPI/Swagger so the interface is adhering to a standard and somewhat future-proof and make use of the time saving features of Serverless.

I’m very much in the research phase so looking for docs/case studies/experiences.

I should note that the applications we will be working on will be made up of various APIs that use various technologies to deliver their functionality. That is to say not all endpoints will be implemented in APIG/Serverless.