Apply Overlays
What Are Overlays?
The Overlay Specification (opens in a new tab) defines a way to create documents to be merged with an OpenAPI description to update it 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 maintain customizations separately.
These customizations can then be applied to an OpenAPI specification in a new file, ensuring that the API specifications remain flexible and adaptive 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 to make to the OpenAPI specification.
With Speakeasy, 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 --before=./openapi_original.yaml --after=./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 suit their needs. You can validate and evaluate your JSONPath expressions here (opens in a new tab).
Anatomy of an Overlay
overlay
Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.
info
titleRequired: Describes the overlay's purpose.versionRequired: 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
titleRequired: Describes the overlay's purpose.versionRequired: 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.