manage-openapi-overlays

OpenAPI overlays allow you to customize specs for SDK generation without editing the source file. By applying overlays using JSONPath targets, you can tailor endpoints, names, and security configurations while preventing drift and preserving source integrity.

An OpenAPI overlay is a customization layer that modifies API specifications using JSONPath targets. You need to use one when you want to adjust operation metadata, group endpoints, or apply settings like retries and pagination without directly altering the original source spec.

To apply and validate overlays, you create an overlay file targeting specific JSONPath elements and apply it to your OpenAPI spec. The validation process verifies the overlay structure, targets, and updates to ensure reliable customization and generate changes automatically.

Yes, you can use speakeasy tooling to create and apply overlays that add security extensions, retries, and pagination to your API operations. This allows you to apply these settings across development workflows without touching the source specification.

The best way to compare OpenAPI specs and generate changes automatically is by validating overlays against the target specification. This process verifies the overlay structure and updates, ensuring reliable transformation and identifying the exact modifications made.

You should use overlays instead of directly modifying your OpenAPI source spec to prevent drift and preserve source integrity. Overlay-based customization lets teams tailor endpoints and settings for SDK generation while keeping the original specification untouched.