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.

About

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

Non-destructive OpenAPI patching via YAML overlays
CLI-driven workflow integration for automated spec regeneration
Automated operation ID suggestion and name overrides
378 GitHub stars
SDK-specific configuration for retries and operation grouping
Metadata enrichment for summaries, descriptions, and tags

Use Cases

Fixing naming inconsistencies in API specs you don't have write access to
Adding missing documentation tags to improve generated SDK usability
Implementing custom retry policies and operation grouping for Speakeasy-generated tools

About

Key Features

Non-destructive OpenAPI patching via YAML overlays
CLI-driven workflow integration for automated spec regeneration
Automated operation ID suggestion and name overrides
378 GitHub stars
SDK-specific configuration for retries and operation grouping
Metadata enrichment for summaries, descriptions, and tags

Use Cases

Fixing naming inconsistencies in API specs you don't have write access to
Adding missing documentation tags to improve generated SDK usability
Implementing custom retry policies and operation grouping for Speakeasy-generated tools