manage-openapi-overlays

Overlays let you customize an OpenAPI spec for SDK generation without modifying the source. This skill covers creating overlay files, applying them to specs, and using them to fix validation errors.

Authentication

Set SPEAKEASY_API_KEY env var or run speakeasy auth login.

When to Use

• You need to customize SDK output but cannot modify the source spec
• Adding x-speakeasy extensions for grouping, naming, or retries
• Fixing lint issues without editing the original file
• Applying an existing overlay file to a spec
• Testing overlay changes before adding to workflow
• Lint errors exist but the source spec cannot be edited
• Adding missing descriptions, tags, or operation names via overlay
• User says: "create overlay", "apply overlay", "customize SDK", "can't modify spec", "fix with overlay"