skills.rest
berea-ch
berea-chOFFICIAL
Explore all skills by this author →
GitHub

manage-openapi-overlays

Create, apply, and validate OpenAPI overlay files with JSONPath expressions.

Updated Feb 23, 2026
Search Tags:#openapi#customization#api specification#sdk generation#overlay#speakeasy
One-click install
npx skills add https://github.com/berea-ch/bereach-sdk-ts --skill manage-openapi-overlays-berea-ch
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: manage-openapi-overlays
Source: https://github.com/berea-ch/bereach-sdk-ts/tree/main/.agents/skills/manage-openapi-overlays
Command: npx skills add https://github.com/berea-ch/bereach-sdk-ts --skill manage-openapi-overlays-berea-ch

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill streamlines the process of customizing OpenAPI specifications by enabling the creation, application, and validation of overlay files, which are essential for tailoring SDK generation without altering the original API definition.

Core Features & Use Cases

  • Overlay Creation: Generate overlay files to define specific modifications to an OpenAPI spec.
  • Overlay Application: Apply existing overlay files to an OpenAPI spec to incorporate customizations.
  • Validation: Ensure overlay files and their syntax are correct before application.
  • Use Case: You need to add custom naming conventions, group related API operations, or configure retry mechanisms for an SDK generated from an OpenAPI spec. This Skill allows you to achieve these customizations using overlay files.

Quick Start

Use the manage-openapi-overlays skill to apply the overlay file 'sdk-overlay.yaml' to the OpenAPI spec 'openapi.yaml' and output the modified spec to 'openapi-modified.yaml'.

Frequently Asked Questions about manage-openapi-overlays

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I customize an OpenAPI spec for SDK generation without altering the original file?▼

OpenAPI overlays let you customize API specifications for SDK generation by applying targeted modifications through JSONPath expressions, keeping the original definition intact while adding custom extensions, grouping, and security schemes.

What is an OpenAPI overlay and when do I need to use one?▼

An OpenAPI overlay is a file containing JSONPath expressions that define specific modifications to an API specification. You need overlays when tailoring SDK generation with custom naming conventions, retries, pagination, or global headers without changing the source spec.

Can I add retry mechanisms and pagination configurations to an OpenAPI spec?▼

Yes, you can add retry mechanisms, pagination configurations, enums, global headers, and custom security schemes to an OpenAPI spec by defining these advanced configurations within an overlay file using custom x-speakeasy extensions.

How do I apply an overlay file to an OpenAPI specification?▼

To apply an overlay, you provide the overlay file and the target OpenAPI spec to merge the customizations. The process validates the overlay syntax and outputs a modified OpenAPI specification incorporating the defined JSONPath changes.

Does this approach support validating overlay syntax before applying it to the API specification?▼

Yes, validation ensures overlay files and their JSONPath syntax are correct before application. This prevents errors during the merging process by checking the overlay structure against the expected OpenAPI specification format.

Related Skills

Explore More Software Engineering Skills→
ehtbantonehtbanton

openapi-spec-builder

Generate OpenAPI 3.x specification files in YAML or JSON format.

Community
Intermediate
speakeasy-apispeakeasy-api
19

improve-sdk-naming

Generate SDK operation ID suggestions from OpenAPI specs via speakeasy suggest.

Official
Intermediate
dhruvinrsonidhruvinrsoni

openapi-specs

Generate, validate, and detect drift in OpenAPI specifications from API code.

Community
Advanced
CarlosEGuerraSilvaCarlosEGuerraSilva

manage-openapi-overlays

Create, apply and validate OpenAPI overlay files with JSONPath targeting for Speakeasy CLI workflows.

Community
Intermediate