Create 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.

View more examples here.

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

Required: Specifies the Overlay Specification version used by the document, currently limited to 1.0.0.

title Required: Describes the overlay’s purpose.
version Required: Identifies the document’s version.

Required: An array of ordered actions for the target document, with at least one object per action.

Required: Specifies a JSONPath query expression to identify the target objects in the target document.

Optional: Brief explanation of the action being performed. Supports CommonMark syntax for rich text representation.

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.

Optional: A boolean value indicating whether the target object should be removed from its map or array. Defaults to false if not specified.

overlay.yaml

overlay: 1.0.0
info:
  title: Overlay to fix the Speakeasy bar
  version: 0.0.1
actions:
  - target: "$.tags"
    description: Add a Snacks tag to the global tags list
    update:
      - name: Snacks
        description: All methods related to serving snacks
  - target: "$.paths['/dinner']"
    description: Remove all paths related to serving dinner
    remove: true