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
Creating an overlay
The easiest way to create an overlay is to use Speakeasy’s Overlay Playground (opens in a new tab). The Overlay Playground provides a GUI for creating and editing overlays.
Make edits to your OpenAPI document and see the corresponding Overlay file get generated automatically.
You can also use the Speakeasy CLI’s compare command to achieve similar results.
speakeasy overlay compare --before=./openapi_original.yaml --after=./openapi.yaml > overlay.yaml
Try Speakeasy's OpenAPI Overlay Playground
For a visual approach to creating or editing overlays, visit overlay.speakeasy.com.