For teams that generate OpenAPI from their codebase, there’s a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file – and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there’s a new generation of tools to make it easy to do, so let’s take a look.

About Overlays

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.

Edit an OpenAPI and save the edits to re-use

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.

Step 2: use the Speakeasy CLI to generate the overlay. The command looks something like this:

speakeasy overlay compare --before museum.yaml --after museum-updated.yaml --out museum-overlay.yaml

This automated way to create overlays is super convenient, because it means you can use any OpenAPI tool to make changes, save the new OpenAPI, and then get an overlay. Try editing with a live OpenAPI docs preview in your IDE or running locally if you are working on documentation and want to make quick changes and save them!

In my example, I changed the server URL to be a localhost entry because I’m running some local tests against an API, here’s the overlay that was generated:

overlay: 1.0.0
info:
title: Overlay museum.yaml => museum-updated.yaml
version: 0.0.0
actions:
- target: $["servers"][0]["url"]
update: http://localhost:8081

Once you make a few edits, you’ll get a longer file, but the point I am trying to illustrate is that it pretty tightly mirrors your OpenAPI file. You can edit this overlay file as you wish, or apply the edits, make more edits, and generate a new Overlay – it’s absolutely safe to work with and is no more mysterious than the OpenAPI format.

Step 3: Add the new overlay file into your repository alongside the OpenAPI file, and add a step to your CI to apply it before the docs are generated (or otherwise as appropriate). I’d recommend running your API linting after applying the changes, to make sure everything is still as expected.

Tips for Overlays

Overlays make sense in multiple places in the API workflow, and I usually characterise them into two rough groups:

• input overlays make your OpenAPI input file ready to be used by the tools in your pipeline. These are steps that add missing error entries, add missing descriptions and licenses, and otherwise patch things up to the standard you want them.
• output overlays prepare an OpenAPI file for a specific destination or tool. For example adding some metadata for your SDK generator to know how to group operations and name the functionality. Or adding code samples or formatting information like x-logo before generating documentation.

At each stage you can have one Overlay or many, and apply them as you wish. The same Overlay might be used for multiple API descriptions if it’s generic enough (such as adding a license or contact information, or setting some tags that are common for all your APIs).

Edit: between writing this post and publishing it, Speakeasy made a very nice Overlay editor tool!! Go to https://overlay.speakeasy.com and try pasting your OpenAPI in the left hand pane. Remove everything in the right hand pane (to reset the overlay) and then start editing in the middle to get the Overlay generated for your edits as you go along. It uses the same tools as the compare command in this post, so feel free to mix and match these tools while you get familiar with Overlays!

In this post, you saw how you can improve an OpenAPI and then keep those improvements when the API changes and the file gets updated. This approach can help you to get the best out of all the OpenAPI tools you use, and I hope it’s helpful! Please leave a comment and let me know how you use Overlays in your own workflow.