manage-openapi-overlays

You can customize an OpenAPI spec without modifying the source by creating and applying an overlay file using the speakeasy CLI. This enables safer experimentation and targeted fixes by layering changes onto the original spec.

An OpenAPI overlay is a JSONPath-based file that applies targeted modifications to a specification. You need it to fix validation issues, attach x-speakeasy extensions, or adjust operation metadata without altering the base OpenAPI document.

To apply an OpenAPI overlay, run the speakeasy CLI command: speakeasy overlay apply -s openapi.yaml -o overlay.yaml --out openapi-modified.yaml. This generates a new spec file with your overlay changes layered on top.

Yes, you can automate OpenAPI overlays by including them in your .speakeasy/workflow.yaml file. This allows automated, layered customizations to run as part of your standard SDK generation pipeline.

You can generate an overlay by comparing an original and modified OpenAPI spec using the speakeasy CLI. This produces a JSONPath-based overlay file that captures the differences, which you can then apply and lint for correctness.

Yes, the speakeasy CLI can lint OpenAPI overlays to validate their correctness. This ensures your JSONPath-based modifications are structurally sound before applying them to your spec for SDK generation.