How can I use OpenAPI overlays to apply white-label branding to API documentation?

How can I use OpenAPI overlays to apply white-label branding to API documentation? #

Platforms operating a white-label or reseller model often expose the same underlying API under multiple brand names, each with its own domain, product name, and support contact. Producing separate hand-maintained OpenAPI documents per brand duplicates effort and guarantees drift as the API evolves. The OpenAPI Overlay Specification allows each brand’s documentation to be generated from one canonical spec with a small, brand-specific overlay.

What Typically Needs to Change per Brand #

info.title and info.description
info.contact and info.termsOfService
servers (brand-specific custom domains)
References to the product name inside operation summaries and descriptions

A Brand Overlay Example #

overlay: 1.0.0
info:
  title: "Acme Reseller Branding Overlay"
  version: 1.0.0
actions:
  - target: $.info
    update:
      title: "Acme Connect API"
      description: "The Acme Connect API lets you manage orders and customers programmatically."
      contact:
        name: "Acme Connect Support"
        email: "support@acmeconnect.example"
        url: "https://acmeconnect.example/support"
      termsOfService: "https://acmeconnect.example/terms"
  - target: $
    update:
      servers:
        - url: "https://api.acmeconnect.example/v1"
          description: "Acme Connect production environment"

Rebranding Operation-Level Text #

If your product name appears inside individual operation descriptions, target those specifically:

  - target: $.paths['/orders'].get
    update:
      description: "List all orders placed through the Acme Connect API."

Structuring Overlays for Many Brands #

For platforms supporting dozens of white-label partners, storing overlays as small, structured YAML per brand — driven by a lightweight partner configuration file rather than hand-written per brand — scales far better:

overlays/
  brand.overlay.acme.yaml
  brand.overlay.contoso.yaml
  brand.overlay.globex.yaml

A generation script can read a brands.json configuration containing just the brand-specific values (name, domain, support email) and template the overlay YAML automatically, rather than requiring a human to hand-edit 30 near-identical files.

Building Documentation per Brand #

for brand in acme contoso globex; do
  redocly join openapi.yaml --overlay "overlays/brand.overlay.$brand.yaml" -o "dist/openapi.$brand.yaml"
  redocly build-docs "dist/openapi.$brand.yaml" -o "dist/docs/$brand/index.html"
done

Each brand’s documentation portal is deployed from its own generated HTML output, with zero manual duplication of the underlying API contract.

Keeping Functional Behavior Identical #

Because the overlay only touches presentational metadata (info, servers, textual descriptions) and never structural elements (paths, schemas, parameters), all brands remain functionally identical under the hood — only the presentation differs, which avoids the risk of accidentally introducing brand-specific behavior bugs.

See What is the OpenAPI Overlay Specification? for the general mechanism, and How can I use OpenAPI overlays to manage multi-tenant API documentation? for a related pattern focused on tenant-specific access rather than branding.

Last updated on July 16, 2026.