manage-openapi-overlays

Files (3)

• SKILL.md
• security-schemes.md · content/
• validation.md · content/

SKILL.md (first lines)

# manage-openapi-overlays

Overlays let you customize an OpenAPI spec for SDK generation without modifying the source. This skill covers creating overlay files, applying them to specs, and using them to fix validation errors.

## Content Guides

| Topic | Guide |
|-------|-------|
| OpenAPI Validation | [content/validation.md](content/validation.md) |
| Security Schemes | [content/security-schemes.md](content/security-schemes.md) |

These guides cover validating specs, fixing common issues, and configuring authentication methods.

## Authentication

Set `SPEAKEASY_API_KEY` env var or run `speakeasy auth login`.

## When to Use

Use this skill when you need to **manually work with overlay files**:

- Creating an overlay file from scratch with specific JSONPath targets
- Applying an existing overlay file to a spec
- Validating overlay syntax and structure
- Comparing two specs to generate an overlay
- Understanding overlay mechanics (actions, targets, update/remove)
- Fixing lint issues via manual overlay creation
- User says: "create overlay", "apply overlay", "overlay file", "manual overlay", "overlay syntax", "JSONPath targeting", "validate overlay"

**NOT for**: AI-powered naming suggestions (see `improve-sdk-naming` instead)

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| Target spec | Yes | OpenAPI spec to customize or fix |
| Customizations | Depends | Changes to apply (groups, names, retries, descriptions) |
| Overlay file | Depends | Existing overlay to apply (for apply workflow) |
| Lint output | Helpful | Validation errors to fix (for fix workflow) |

## Outputs

| Output | Description |
|--------|-------------|
| Overlay file | YAML file with JSONPath-targeted changes |
| Modified spec | Transformed OpenAPI spec (when applying) |

## Commands

### Generate an Overlay by Comparing Specs

```bash
speakeasy overlay compare -b <before-spec> -a <after-spec> -o <output-overlay>
```

Use this when you have a modified version of a spec and want to capture the differences as a reusable overlay.

### Apply an Overlay to a Spec

```bash
speakeasy overlay apply -s <spec-path> -o <overlay-path> --out <output-path>
```

### Validate an Overlay

```bash
speakeasy overlay validate -o <overlay-path>
```

## Creating an Overlay Manually

Create an overlay file with this structure:

```yaml
overlay: 1.0.0
info:
  title: My Overlay
  version: 1.0.0
actions:
  - target: "$.paths['/example'].get"
    update:
      x-speakeasy-group: example
      x-speakeasy-name-override: getExample
```

Each action has a `target` (JSONPath expression) and an `update` (object to merge) or `remove` (boolean to delete the target).

## Example: SDK Method Naming and Grouping

```yaml
overlay: 1.0.0
info:
  title: SDK Customizations
  version: 1.0.0
actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: list
  - target: "$.paths['/users'].post"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: create
  - target: "$.paths['/users/{id}'].get"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: get
  - target: "$.paths['/users/{id}'].delete"
    update:
      x-speakeasy-group: users
      x-speakeasy-name-override: delete
      deprecated: true
```

This produces SDK methods: `sdk.users.list()`, `sdk.users.create()`, `sdk.users.get()`, `sdk.users.delete()`.

## Example: Apply Overlay

```bash

From speakeasy-api/sdk-generation-skills, Apache-2.0.

More from speakeasy-api/sdk-generation-skills