apply-openapi-overlay

Apply an overlay file to transform an OpenAPI spec.

When to Use

• You have an overlay file ready to apply to a spec
• Testing overlay changes before adding to workflow
• User says: "apply overlay", "merge overlay", "overlay apply"

Inputs

Input	Required	Description
OpenAPI spec	Yes	Source spec (-s)
Overlay file	Yes	Overlay to apply (-o)

Outputs

Output	Description
Modified spec	Transformed OpenAPI spec (--out)

Command

speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>

Example

# Apply overlay and output merged spec
speakeasy overlay apply -s openapi.yaml -o my-overlay.yaml --out openapi-modified.yaml

Using in Workflow (Recommended)

Better approach - add overlay to workflow.yaml:

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml

Overlays are applied in order, so later overlays can override earlier ones.

Troubleshooting

Error	Cause	Solution
"target not found"	JSONPath doesn't match	Verify path exists in spec with exact casing
"invalid overlay"	Malformed YAML	Check overlay structure matches spec
No changes applied	Wrong target path	Use $.paths['/exact-path'] syntax

Related Skills

• create-openapi-overlay - Create overlay files
• regenerate-sdk - Run workflow with overlays applied
• fix-validation-errors-with-overlays - Use overlays to fix lint issues