Overlays

What Are Overlays ?

The Overlay (opens in a new tab) specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

Overlays are particularly useful in scenarios where the same API specification is used for multiple purposes across different workflows or teams. Instead of making direct changes to the primary spec or needing to manage multiple versions, overlays allow you to maintain customizations separately.

These customizations can then be applied to an OpenAPI specification in a new file, ensuring that your API specifications remain flexible and adaptive to your organizational needs without altering the core document.

Common Use Cases

Overlays enable a variety of customizations to API specifications. Common scenarios include:

• Adding Speakeasy extensions: Enhance API specs with custom Speakeasy extensions for additional functionality or metadata.
• Adding examples to API documentation: Provide clear, concrete examples to clarify API usage.
• Hiding internal APIs from a public SDK: Exclude internal API endpoints from public-facing SDK documentation for security and clarity.

View more examples here.

Creating an Overlay

Create an overlay by creating a new YAML document that details the specific alterations you want to make to your OpenAPI specification. This document acts as a blueprint for modifying your API.

With Speakeasy, you can create overlays manually or automatically.

For a quick generation of differences between two API versions, use the compare command in the Speakeasy CLI.

Using compare

The compare feature is designed to assist in identifying differences across OpenAPI documents. However, users requiring precise adjustments may need to manually edit the generated overlay file to their needs. You can validate and evalute your JSONPath expressions here (opens in a new tab).

Applying an Overlay

Install the Speakeasy CLI and use the overlay command.

1. Install Speakeasy CLI:

2. Validate the Overlay:

Validate the overlay before applying it to ensure it adheres to the OpenAPI Overlay specification. Use the following command:

This command checks your overlays.yaml file and lets you know if it meets the OpenAPI Overlay specification.

3. Applying the Overlay:

Apply your overlay to your OpenAPI document with the following command, replacing input-openapi.yaml with the path to your original OpenAPI spec file and overlays.yaml with the path to your overlay file:

This command merges the changes defined in your overlay file with your original OpenAPI spec and outputs the results to a new file named combined.yaml.

4. Review the Merged Results:

View the merged results of your overlay on the OpenAPI document in the combined.yaml file. This file contains your original OpenAPI spec updated with the modifications specified in your overlay. We recommend you review this file to ensure the changes are applied as expected.

Adding an Overlay to your Speakasy Workflow

The Speakeasy workflow can accept an overlay file as an input in a source, allowing you to apply customizations to your OpenAPI document as part of your Speakeasy workflow. For more information on how sources work see here.

Once you have a valid overlay file, you can add it to your Speakeasy workflow file by running speakeasy configure sources.

Choose an existing source or create a new one

Confirm the location of your source document

When prompted, provide the path to your overlay file.

Optionally provide a location for the output build of your OpenAPI document and the overlay.

The overlay will now be applied to your OpenAPI document as part of your Speakeasy workflow. Run speakeasy run to run your workflow.

Anatomy of an Overlay