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開発

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.

主な機能

378 GitHub stars
Create overlay templates from existing OpenAPI specifications
Customize operation names and group endpoints for cleaner SDK method signatures
Apply portable patches that work across different versions of a source specification
Add SDK-specific configurations like retry logic and deprecation tags non-destructively
Target specific endpoints and schemas using precise JSONPath syntax

ユースケース

Refining a third-party API spec for better client-side method naming without ownership of the source
Adding descriptions and grouping to a generated spec to improve SDK discoverability
Marking specific endpoints as deprecated for SDK users without affecting the underlying API service

概要

主な機能

378 GitHub stars
Create overlay templates from existing OpenAPI specifications
Customize operation names and group endpoints for cleaner SDK method signatures
Apply portable patches that work across different versions of a source specification
Add SDK-specific configurations like retry logic and deprecation tags non-destructively
Target specific endpoints and schemas using precise JSONPath syntax

ユースケース

Refining a third-party API spec for better client-side method naming without ownership of the source
Adding descriptions and grouping to a generated spec to improve SDK discoverability
Marking specific endpoints as deprecated for SDK users without affecting the underlying API service