manage-openapi-overlays（管理 openapi 覆盖）

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

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

Outputs

Commands

Generate an Overlay by Comparing Specs

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

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

Validate an Overlay

speakeasy overlay validate -o <overlay-path>

Creating an Overlay Manually

Create an overlay file with this structure:

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

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

# Apply overlay and write merged spec
speakeasy overlay apply -s openapi.yaml -o sdk-overlay.yaml --out openapi-modified.yaml

# Compare two specs to generate an overlay
speakeasy overlay compare -b original.yaml -a modified.yaml -o changes-overlay.yaml

Using in Workflow (Recommended)

Instead of applying overlays manually, add them to .speakeasy/workflow.yaml:

sources:
  my-api:
    inputs:
      - location: ./openapi.yaml
    overlays:
      - location: ./naming-overlay.yaml
      - location: ./grouping-overlay.yaml

Overlays are applied in order. Later overlays can override earlier ones. This approach ensures overlays are always applied during speakeasy run.

Common Fix Patterns

Use overlays to fix validation issues when you cannot edit the source spec.

Fix Workflow

# 1. Validate the spec to identify issues
speakeasy lint openapi --non-interactive -s openapi.yaml

# 2. Create an overlay file targeting each issue (see patterns above)

# 3. Add overlay to workflow.yaml under sources.overlays

# 4. Regenerate the SDK
speakeasy run --output console

Speakeasy Extensions Reference

Extensions (x-speakeasy-*) customize SDK generation. Apply them via overlays.

Retries

actions:
  - target: "$.paths['/resources'].get"  # Or "$" for global
    update:
      x-speakeasy-retries:
        strategy: backoff
        backoff:
          initialInterval: 500      # ms
          maxInterval: 60000        # ms
          maxElapsedTime: 3600000   # ms
          exponent: 1.5
        statusCodes: ["5XX", "429"]
        retryConnectionErrors: true

Pagination

Offset/Limit:

actions:
  - target: "$.paths['/users'].get"
    update:
      x-speakeasy-pagination:
        type: offsetLimit
        inputs:
          - name: offset
            in: parameters
            type: offset
          - name: limit
            in: parameters
            type: limit
        outputs:
          results: $.data
          numPages: $.meta.total_pages

Cursor:

actions:
  - target: "$.paths['/events'].get"
    update:
      x-speakeasy-pagination:
        type: cursor
        inputs:
          - name: cursor
            in: parameters
            type: cursor
        outputs:
          results: $.events
          nextCursor: $.next_cursor

Open Enums (Anti-Fragility)

Prevent SDK breakage when APIs return new enum values:

actions:
  - target: "$.components.schemas.Status"
    update:
      x-speakeasy-unknown-values: allow

For all enums (add x-speakeasy-jsonpath: rfc9535 at overlay root):

actions:
  - target: $..[?length(@.enum) > 1]
    update:
      x-speakeasy-unknown-values: allow

Global Headers

Add SDK-wide headers as constructor options:

actions:
  - target: $
    update:
      x-speakeasy-globals:
        parameters:
          - $ref: "#/components/parameters/TenantId"
  - target: $.components
    update:
      parameters:
        TenantId:
          name: X-Tenant-Id
          in: header
          schema:
            type: string

Result: client = SDK(api_key="...", tenant_id="tenant-123")

Custom Security Schemes

For complex auth (HMAC, multi-part credentials):

actions:
  - target: $.components
    update:
      securitySchemes:
        hmacAuth:
          type: http
          scheme: custom
          x-speakeasy-custom-security-scheme:
            schema:
              type: object
              properties:
                keyId:
                  type: string
                keySecret:
                  type: string
  - target: $
    update:
      security:
        - hmacAuth: []

With envVarPrefix: MYAPI in gen.yaml, generates env var support for MYAPI_KEY_ID, MYAPI_KEY_SECRET.

JSONPath Targeting Reference

What NOT to Do

• Do NOT use overlays for invalid YAML/JSON syntax errors -- fix the source file
• Do NOT try to fix broken $ref paths with overlays -- fix the source spec
• Do NOT use overlays to fix wrong data types -- this is an API design issue
• Do NOT try to deduplicate schemas with overlays -- requires structural analysis
• Do NOT ignore errors that require source spec fixes -- overlays cannot solve everything
• Do NOT modify source OpenAPI specs directly if they are externally managed
• Do NOT use a speakeasy overlay create command -- it does not exist

Troubleshooting

After Making Changes

After creating or modifying overlay files and adding them to workflow.yaml, prompt the user to regenerate the SDK:

Overlay configuration complete. Would you like to regenerate the SDK now with speakeasy run?

If the user confirms, run:

speakeasy run --output console

Overlay changes only take effect in the SDK after regeneration.