Decoupling dev and docs with OpenAPI Overlays

On October 22, 2024, the OpenAPI initiative officially announced the publication of the OpenAPI Overlay Specification version 1.0.0. Although this may not sound like much to many people and even though Overlays were already available under an “experimental” label, the official release may set the stage for wider adoption and positioning of Overlays as the missing piece of the “document an API” puzzle.

Is OpenAPI for tech writers?

I firmly believe that a tech writer, even one who spends most of their time documenting software that has a user interface, should be comfortable documenting content that is not primarily meant to be read by humans. This is where you get to justify the “technical” in “technical writer” and OpenAPI specifications are no exception to that. Even more so as they are a single and very versatile source of truth that can be used to implement calls to an API manually, but also to generate documentation or API clients automatically. A properly created and documented OpenAPI specification can go a long way when it comes to user satisfaction and increase in numbers.

Why one more file?

Let’s get straight to the point—OpenAPI specifications can be huge. For a poorly segmented and structured all-in-one API spec, this can mean thousands of lines, maybe even tens of thousands. Yes, I’ve seen it. If we’re going to measure who caught a larger fish, mine had almost 30K lines and I believe there are lots of bigger fish swimming near the dark bottom of API development seas. Trying to navigate and edit one of these can turn your life into endless scrolling, (cmd+F)-ing, and squinting to find the right place to add a line or make an update. All this while hoping that you don’t break the whole thing.

To make things worse, the way OpenAPI specs are generated or created can complicate things further. Both automatic generation and manual contribution by a number of different people can cause trouble even with well defined processes and git workflows. Sometimes this is more than enough to discourage technical writers from contributing to an API specification directly, or developers from letting our code-ignorant fingers anywhere near a spec in a git repository.

So, what is an Overlay?

To put it simply, it’s an API specification file that adds to, modifies, or removes things from another OpenAPI specification. An Overlay is separate from the “main” specification that shows the structure and the essential elements of an API, and just references those elements to provide further information about them or how they should be handled once the Overlay is applied. This opens up the possibility for documentation authors to keep their contributions to an OpenAPI specification separate and well organized as there is no noise from the technical and structural API details, while not adding significant complexity to how the end result is achieved as the process of applying an Overlay is fairly simple and can be a single automated step in a CI/CD pipeline.

How does it work in practice?

The OpenAPI Initiative GitHub currently lists four tools that can work with Overlays. Out of the four, I chose Apigee Go Gen CLI, their Petstore OAS3 example, and targeted Overlay to do a small-scale test. Before showing the CLI in action, let’s briefly review what the Overlay showcases in its 23 lines:

overlay: 1.0.0
info:
  title: Targeted Overlay
  version: 1.0.0
extends: petstore.yaml
actions:
  - target: $.info.contact
    remove: true
  - target: $.info
    update:
      description: This is a new description
  - target: $.tags[?(@.name=='pet')]
    update:
      externalDocs:
        url: https://example.com/pet
  - target: $.paths['/pet/{petId}/uploadImage'].post
    update:
      description: This is the new description for uploadImage operation
  - target: $.paths['/pet/{petId}']
    update:
      get:
        description: This is an updated description of a child object
        x-safe: false

At the very beginning of the file, the overlay field provides the version number of the Overlay specification, while info includes the title and version number of the specific document. The extends property is not mandatory, but is convenient as you can specify the path to the document this Overlay applies to, which will simplify the command line later on as you will not have to specify it again. Finally, the actions object contains what Overlays are about—the nodes in the “main” specification and the way they should be amended, modified, or, if needed, maybe even removed.

Once you have an OpenAPI specification and an Overlay, it’s a matter of executing a single command to apply the Overlay to the spec file and generate a single OpenAPI specification that contains both the original spec and the content of the Overlay. This is the syntax of the Apigee Go Gen transform oas-overlay command that applies the Overlay:

apigee-go-gen transform oas-overlay \
  --spec petstore.yaml \
  --overlay overlay.yaml \
  --output out/petstore-overlaid.yaml

Note that this command would also work without the --spec petstore.yaml line, as the Overlay file already includes the extends property that specifies which OpenAPI specification file it targets.

The end result of the action is the petstore-overlaid.yaml file in the out directory, which is the final OpenAPI specification that includes both the content from petstore.yaml and the additions provided in the Overlay. You can now provide the output file to the API reference documentation generator of your choice and build the final output.

Verdict

Before presenting my opinion on whether Overlays should make authoring of API docs easier, here are some pros and cons that I identified.

Final thoughts

Based on my previous experience with management of large single-file OpenAPI specifications, Overlays seem as a great way to divide and physically decouple tasks and responsibilities related to creating and documenting an API, without having engineering and technical writing teams stepping on each other’s toes. The added complexity by having to manage multiple files is, in my opinion, way more than justified and worth the extra independence that technical writers have when it comes to adding documentation.

Resources

• OpenAPI Overlay Specification
• OpenAPI Overlay Specification GitHub
• Apigee Go Gen CLI