Create overlays

What are overlays?

The Overlay Specification (opens in a new tab) defines a way to create overlay documents to be merged with an OpenAPI document to update it with additional information.

Overlays are particularly useful in scenarios where the same OpenAPI document serves multiple purposes across different workflows or teams. Instead of making direct changes to the primary spec or managing multiple versions, overlays maintain customizations separately.

These customizations apply to an OpenAPI document in a new file, ensuring API specifications remain flexible and adaptive without altering the core document.

Common use cases

Overlays enable various customizations to API specifications. Common scenarios include:

Adding Speakeasy extensions: Enhance OpenAPI documents 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 writing a new YAML document that specifies the modifications to the OpenAPI document.

Speakeasy supports both manual and automatic overlay creation.

Generate the differences between two OpenAPI document versions with the compare command in the Speakeasy CLI.

speakeasy overlay compare --before=./openapi_original.yaml --after=./openapi.yaml > overlay.yaml

Using compare

The compare feature helps identify differences across OpenAPI documents. Precise adjustments may require manual refinement of the generated overlay file. Validate and evaluate 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 merge 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 to remove the target object 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

Helpful references:

Try Speakeasy's OpenAPI Overlay Playground

For a visual approach to creating or editing overlays, visit overlay.speakeasy.com.