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.
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.
speakeasy overlay compare --schemas=./openapi_original.yaml --schemas=./openapi.yaml > overlay.yaml
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:
brew install speakeasy-api/homebrew-tap/speakeasy
2. Validate the Overlay:
Validate the overlay before applying it to ensure it adheres to the OpenAPI Overlay specification. Use the following command:
speakeasy overlay validate -o overlays.yaml
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:
speakeasy overlay apply -s input-openapi.yaml -o overlays.yaml > combined.yaml
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
overlay
Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.
info
title
Required: Describes the overlay's purpose.version
Required: Identifies the document's version.
actions
Required: An array of ordered actions for the target document, with at least one object per action.
target
Required: Specifies a JSONPath query expression to identify the target objects in the target document.
description
Optional: Brief explanation of the action being performed. Supports CommonMark syntax for rich text representation.
update
Optional: Defines the properties and values to be merged with the objects identified by the target. This property is disregarded if the remove
property is set to true
.
remove
Optional: A boolean value indicating whether the target object should be removed from its map or array. Defaults to false
if not specified.
overlay
Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.
info
title
Required: Describes the overlay's purpose.version
Required: Identifies the document's version.
actions
Required: An array of ordered actions for the target document, with at least one object per action.
target
Required: Specifies a JSONPath query expression to identify the target objects in the target document.
description
Optional: Brief explanation of the action being performed. Supports CommonMark syntax for rich text representation.
update
Optional: Defines the properties and values to be merged with the objects identified by the target. This property is disregarded if the remove
property is set to true
.
remove
Optional: A boolean value indicating whether the target object should be removed from its map or array. Defaults to false
if not specified.