How can I use OpenAPI overlays to inject vendor extensions for SDK generation?

How can I use OpenAPI overlays to inject vendor extensions for SDK generation? #

Tools like openapi-generator and Speakeasy read vendor-specific x- extension fields to control exactly how generated SDKs look: method names, module groupings, retry behavior, pagination helpers, and more. These extensions are meaningful only to the code generator — they add noise for anyone just reading the API contract. The OpenAPI Overlay Specification lets you inject them at generation time, keeping the canonical document generator-agnostic.

Why Keep Generator Config Out of the Base Spec #

Different generators expect different extension names and structures. If you support multiple SDK toolchains (say, one for TypeScript and one for Go), embedding both sets of vendor extensions directly in the base document creates clutter and coupling to specific tools. An overlay per generator keeps each concern isolated.

Adding `x-codegen` Naming Hints #

overlay: 1.0.0
info:
  title: TypeScript SDK Generator Overlay
  version: 1.0.0
actions:
  - target: $.paths['/users/{id}'].get
    update:
      operationId: "getUserById"
      x-codegen-request-body-name: "body"
  - target: $.components.schemas.User
    update:
      x-typescript-type: "UserRecord"

Controlling Client Grouping With Tags #

Many generators group generated client methods by tags. An overlay can normalize tags specifically for SDK output without changing the tags shown in human-facing documentation:

  - target: $.paths['/orders'].*
    update:
      x-sdk-group: "OrdersClient"

Adding Pagination and Retry Hints #

Some generators support custom pagination or retry strategies via extensions:

  - target: $.paths['/orders'].get
    update:
      x-pagination:
        style: "cursor"
        cursorParam: "pageToken"
        limitParam: "pageSize"
      x-retryable: true

Per-Language Overlay Files #

A typical structure keeps one overlay per target language, since naming conventions and idioms differ:

overlays/
  sdk.overlay.typescript.yaml
  sdk.overlay.go.yaml
  sdk.overlay.python.yaml

Your build pipeline applies the right overlay before invoking the generator for that language:

redocly join openapi.yaml --overlay overlays/sdk.overlay.go.yaml -o build/openapi.go.yaml
openapi-generator-cli generate -i build/openapi.go.yaml -g go -o clients/go

Avoiding Collisions With Documentation Overlays #

If you also maintain a documentation-focused overlay (for examples or localized text), apply overlays in a defined order, or merge multiple overlays into the pipeline sequentially, so that SDK-only extensions never leak into the public documentation output, and vice versa.

Validating Generator Output #

Because vendor extensions are opaque to standard OpenAPI validators, add a smoke test to your pipeline that actually runs the generator against the overlaid document and confirms the SDK builds successfully. This catches typos in extension names or malformed values before they reach a release.

See What is the OpenAPI Overlay Specification? for the base mechanism, and How can I use OpenAPI overlays to rename operationIds for SDK consistency? for a closely related technique.

Last updated on July 16, 2026.