Does this skill handle schema deduplication?

No, overlays are designed for targeting and updating specific nodes. Complex structural changes like deduplication require deeper structural analysis beyond the scope of simple overlays.

Can I use this to fix bugs in a third-party API spec?

Yes, overlays are the ideal tool for correcting errors, adding missing summaries, or fixing type issues in specifications that you do not have write access to.

What is an OpenAPI overlay?

An OpenAPI overlay is a specialized document that describes modifications or additions to an OpenAPI specification without altering the original source file, primarily used to tailor SDK generation.

Is this skill compatible with the Speakeasy CLI?

Yes, it is specifically designed to work with Speakeasy to produce overlays that integrate seamlessly with their SDK generation pipeline.

How do I target specific parts of my API with this skill?

The skill utilizes JSONPath syntax, allowing you to select specific paths (e.g., $.paths['/users'].get), components, or the general info object to apply updates.

OpenAPI Overlay Creator

Name: OpenAPI Overlay Creator
Author: speakeasy-api

byspeakeasy-api

•

378

•

API Development

Generates and manages OpenAPI overlays to customize SDK generation without modifying the original API specification.

The OpenAPI Overlay Creator skill empowers developers to refine and enhance their API documentation for SDK generation using Speakeasy. By creating portable overlay files, you can rename operations, group endpoints, and add SDK-specific extensions like retry logic or deprecation notices without altering the source OpenAPI file. This is particularly useful when working with third-party APIs or when maintaining a clean separation between the core API contract and SDK-specific presentation layers, ensuring your generated client libraries are idiomatic and user-friendly.

Key Features

01378 GitHub stars

02Create overlay templates from existing OpenAPI specifications

03Customize operation names and group endpoints for cleaner SDK method signatures

04Apply portable patches that work across different versions of a source specification

05Add SDK-specific configurations like retry logic and deprecation tags non-destructively

06Target specific endpoints and schemas using precise JSONPath syntax

Use Cases

01Refining a third-party API spec for better client-side method naming without ownership of the source

02Adding descriptions and grouping to a generated spec to improve SDK discoverability

03Marking specific endpoints as deprecated for SDK users without affecting the underlying API service

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add speakeasy-api/speakeasy create-openapi-overlay

For use in Claude.ai and ChatGPT

Download Skill