Edit With Overlays

Overlays (opens in a new tab) 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:

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.


speakeasy overlay compare --schemas=./openapi­_original.yaml --schemas=./openapi.yaml > overlay.yaml

Info Icon

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.

Anatomy of an Overlay

overlay

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

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

info

  • title Required: Describes the overlay's purpose.
  • version Required: Identifies the document's version.
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

actions

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

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

target

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

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

description

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

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

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.

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

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

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

Applying an Overlay

Install the Speakeasy CLI and use the overlay command.

1. Install Speakeasy CLI:


brew install speakeasy-api/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.