Save edits to OpenAPI as an Overlay
An Overlay is a set of amendments to be made to an OpenAPI description. It is an ordered series of steps, where each step can add, update or remove elements from the OpenAPI description.
An Overlay is applied to an OpenAPI description – and the output is an (improved) OpenAPI description. OpenAPI is always the interchange format between the tools that you use in your API description pipeline, and so you can add an Overlay, or many of them, at any point in the process.
Common examples might be to add descriptions to a generated OpenAPI file that doesn’t have much user-friendly content in it but describes the API and data structures, to remove private endpoints before publishing documentation, or to add extra fields for your SDK generator or API gateway tools.
Step 1: edit the OpenAPI file! Make it awesome, add links to descriptions and fill in multiple response examples without using either “foo” or “bar”. Generally, go wild :) If you would like something to test with, I’m using the Museum API.
