Editing with Overlays
Overlays (opens in a new tab) are a convenient way to change your OpenAPI spec without having to make the changes directly in the source file. This can be useful when you want to make changes to a spec that is being used in multiple workflows, or when you want to make changes to a spec that is generated from code.
Overlay take the form of an overlay document. The document contains an ordered list of Action objects which describe the desired alteration are to be applied to the spec. Each Action Object has a target property and a modifier type (update or remove). The target property is a JSONPath query expression that identifies the elements of the target document to be updated and the modifier determines the change.
In many ways, this is similar to JSONPatch (opens in a new tab), but without the requirement to use a single explicit path for each operation. This allows the creator of an overlay file to apply a single modification to a large number of nodes in the file within a single operation.
Anatomy of an Overlay
overlay
REQUIRED. This string MUST be the version number of the Overlay Specification that the Overlay document uses. The overlay field is used by tooling to interpret the Overlay document. For now the only valid value is 1.0.0.
info
REQUIRED - the object provides metadata about the Overlay.
title- REQUIRED. A human readable description of the purpose of the overlay.version- REQUIRED. A version identifer for indicating changes to the Overlay document.
actions
REQUIRED An ordered list of actions to be applied to the target document. The array MUST contain at least one object. Each object represents one or more changes to be applied to the target document at the location defined by the target's JSONPath expression.
target
REQUIRED A JSONPath query expression referencing the target objects in the target document.
description
Optional A description of the action. CommonMark syntax may be used for rich text representation.
update
Optional An object with the properties and values to be merged with the object(s) referenced by the target. This property has no impact if remove property is true.
remove
Optional A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false.
overlay
REQUIRED. This string MUST be the version number of the Overlay Specification that the Overlay document uses. The overlay field is used by tooling to interpret the Overlay document. For now the only valid value is 1.0.0.
info
REQUIRED - the object provides metadata about the Overlay.
title- REQUIRED. A human readable description of the purpose of the overlay.version- REQUIRED. A version identifer for indicating changes to the Overlay document.
actions
REQUIRED An ordered list of actions to be applied to the target document. The array MUST contain at least one object. Each object represents one or more changes to be applied to the target document at the location defined by the target's JSONPath expression.
target
REQUIRED A JSONPath query expression referencing the target objects in the target document.
description
Optional A description of the action. CommonMark syntax may be used for rich text representation.
update
Optional An object with the properties and values to be merged with the object(s) referenced by the target. This property has no impact if remove property is true.
remove
Optional A boolean value that indicates that the target object is to be removed from the the map or array it is contained in. The default value is false.
Applying an Overlay
If you want to try it for yourself , you can install the Speakeasy CLI and use our overlay command:
brew install speakeasy-cli
speakeasy overlay apply -s input-openapi.yaml -o overlays.yaml >> combined.yaml
An Example
In this example we're going to make some simple edits to this OpenAPI spec using overlays.
We will remove all the operations associated with the /dinner endpoint and add a new tag called snacks.
Adding a tag
Specify that we want to add a new tag to the global tags list $.tags and add a description of the edit you're making.
Under the update label, add the name and description of the tag you want to add.
Removing an endpoint
For a remove action, we specify the target path for the endpoint and set the remove property to true.
The results
You can see that the edits we specified in the overlay have been applied to the resulting OpenAPI spec.
In this example we're going to make some simple edits to this OpenAPI spec using overlays.
We will remove all the operations associated with the /dinner endpoint and add a new tag called snacks.
Adding a tag
Specify that we want to add a new tag to the global tags list $.tags and add a description of the edit you're making.
Under the update label, add the name and description of the tag you want to add.
Removing an endpoint
For a remove action, we specify the target path for the endpoint and set the remove property to true.
The results
You can see that the edits we specified in the overlay have been applied to the resulting OpenAPI spec.