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.yamlUsing 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.yamlOverlays 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 filesregenerate-sdk- Run workflow with overlays appliedfix-validation-errors-with-overlays- Use overlays to fix lint issues