When should I use an overlay instead of editing the source?

Use an overlay when you don't have permission to edit the source spec, when the spec is auto-generated, or when you need to add tool-specific metadata like SDK retry logic.

How do I apply these fixes with Speakeasy?

You can generate suggestions using 'speakeasy suggest', add the resulting overlay to your workflow.yaml, and then run 'speakeasy run' to apply the changes.

Can this skill fix invalid JSON or YAML syntax?

No, structural syntax errors or broken references must be fixed in the source file before an overlay can be applied.

What is an OpenAPI overlay?

An OpenAPI overlay is a document that describes modifications to an existing API specification without directly editing the source file, allowing for cleaner version control and maintenance.

OpenAPI Overlay & Validation Fixer

Name: OpenAPI Overlay & Validation Fixer
Author: speakeasy-api

byspeakeasy-api

•

378

•

API Development

Resolves OpenAPI linting and validation errors by applying non-destructive overlays to source specifications.

This skill streamlines the process of improving OpenAPI specifications using Speakeasy overlays, allowing you to fix linting errors and enhance API metadata without modifying the original source file. It is ideal for developers who need to refine third-party specs or maintain a clean separation between the core API contract and SDK-specific enhancements. The skill guides you through generating operation ID suggestions, adding missing documentation, grouping operations, and configuring retry logic, ensuring that your generated SDKs and Terraform providers are polished and type-safe.

Key Features

01Non-destructive OpenAPI patching via YAML overlays

02CLI-driven workflow integration for automated spec regeneration

03Automated operation ID suggestion and name overrides

04378 GitHub stars

05SDK-specific configuration for retries and operation grouping

06Metadata enrichment for summaries, descriptions, and tags

Use Cases

01Fixing naming inconsistencies in API specs you don't have write access to

02Adding missing documentation tags to improve generated SDK usability

03Implementing custom retry policies and operation grouping for Speakeasy-generated tools

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add speakeasy-api/speakeasy fix-validation-errors-with-overlays

For use in Claude.ai and ChatGPT

Download Skill