OpenAPI Overlays
Overlays allow us to modify an existing OpenAPI document without directly editing the original document. An overlay is a separate document that contains instructions for updating the original OpenAPI document.
Active Development
The OpenAPI Overlay
Specification
Overlays are useful for:
- Separating concerns between the original API definition and modifications required by different consumers or use cases.
- Avoiding direct modification of the original OpenAPI document, which may be managed by a separate team or process.
- Applying a set of common modifications to multiple OpenAPI documents.
Overlay Document Structure in OpenAPI
An Overlay document is a separate document from the OpenAPI document it modifies. It contains an ordered list of Action Objects that describe the modifications to be made to the original OpenAPI document.
Overlay Document Structure
The following sections describe the structure of an Overlay document:
overlay
The version of the Overlay Specification that the document uses. The value must be a supported version number
info
Field Name | Type | Required |
---|---|---|
info | Info Object | ✅ |
Provides metadata about the Overlay document.
title
Field Name | Type | Required |
---|---|---|
title | String | ✅ |
A human-readable title describing the purpose of the Overlay document.
version
A version identifier indicating the version of the Overlay document.
actions
Field Name | Type | Required |
---|---|---|
actions | [Action Object] | ✅ |
An ordered list of Action Objects to be applied to the original OpenAPI document. The list must contain at least one Action Object.
target
Field Name | Type | Required |
---|---|---|
version | String | ✅ |
A JSONPath
description
Field Name | Type | Required |
---|---|---|
version | String |
A description of the action. This may contain CommonMark syntax
update
Field Name | Type | Required |
---|---|---|
version | String |
An object containing the properties and values to be merged with the objects referenced by the target
. This field has no effect if the remove
field is true
.
remove
Field Name | Type | Required |
---|---|---|
version | String |
If true
, the objects referenced by the target
are removed from the original document. If false
or not provided, the objects are not removed. This field takes precedence over the update
field.
Overlay Specification Versions
The overlay
field contains the version number of the Overlay Specification that the document conforms to. Tooling should use this value to interpret the document correctly.
The current version of the Overlay Specification is 1.0.0
, but keep in mind that the specification is still under development.
Overlay Info Object in OpenAPI
Provides metadata about the Overlay document.
Action Object in OpenAPI
Each Action Object represents at least one change to be made to the original OpenAPI document at the location specified by the target
field.
Action Targets in OpenAPI
The target
field of an Action Object is a JSONPath
JSONPath expressions allow you to select and manipulate specific parts of a JSON or YAML document using an intuitive syntax. The expressions are similar to XPath for XML, allowing you to traverse the document tree and select elements based on various criteria.
JSONPath is implemented differently
Here are some examples of JSONPath expressions relevant to OpenAPI documents:
When selecting the object to target for different types of updates, consider the following:
For example, to update the description
field of the info
object, you would target the info
object itself:
To remove a specific path, such as /oldDrinks
, from the paths
object, you would target that path directly:
Applying an Overlay in OpenAPI
When an overlay is applied, the update
object is merged with the targeted objects. Any properties present in both the update
object and the targeted objects will be replaced with the values from the update
object. New properties from the update
object will be added to the targeted objects.
The Overlay document is processed in the following order:
-
Tooling locates the original OpenAPI document to modify. This is based on the
extends
field if provided, otherwise determined by the tooling. -
Each Action Object is applied to the OpenAPI documents in the order they appear in the
actions
array.For each action:
-
The
target
JSONPath expression is evaluated against the OpenAPI document to locate the objects to modify. -
If the
remove
field istrue
, the targeted objects are removed from the OpenAPI document. -
If the
remove
field isfalse
or not provided and anupdate
object is specified, theupdate
object is merged with each of the targeted objects.
-
OpenAPI Overlay Examples
Here are some examples of overlays that could be applied to the Speakeasy Bar OpenAPI document:
Updating Info and Servers
This example demonstrates updating the info
and servers
objects in the original OpenAPI document.
Adding Tags and Updating Drink Responses
This example demonstrates adding tags to the OpenAPI document and updating response objects for operations related to drinks.
Adding Query Parameter Tags
This example demonstrates adding a tag to all operations that have query parameters.
Removing Deprecated Drink Operations
This example demonstrates removing operations related to drinks that have been marked as deprecated.
Overlay Creation Tool
Check out overlay.speakeasy.com to create and edit your overlays visually.
Last updated on