How can I use OpenAPI overlays to generate audience-specific API documentation?

How can I use OpenAPI overlays to generate audience-specific API documentation? #

A single API rarely has just one audience. Internal engineers need exhaustive technical detail, partners need a curated subset with business context, and the general public needs a simplified, friendly view. Maintaining three (or more) hand-edited copies of an OpenAPI document is unsustainable. The OpenAPI Overlay Specification allows each audience-specific view to be expressed as its own overlay, applied on demand to the same canonical source.

Designing the Canonical Document #

The canonical document should contain the union of everything any audience might need — full technical descriptions, internal notes as x- extensions, and every endpoint, including internal-only ones. Audience-specific overlays then subtract or transform, never add net-new capability.

paths:
  /internal/admin/audit-log:
    get:
      x-internal: true
      summary: Retrieve the raw audit log
  /orders:
    get:
      summary: List orders
      x-internal-note: "Backed by the orders-service read replica."

Overlay for Internal Engineers #

The internal overlay generally does very little — perhaps just adding links to runbooks:

overlay: 1.0.0
info:
  title: Internal Engineering Overlay
  version: 1.0.0
actions:
  - target: $.paths['/orders'].get
    update:
      description: "See the runbook at https://wiki.internal/orders-service for on-call guidance."

Overlay for External Partners #

The partner overlay removes internal endpoints and internal notes, and may rewrite summaries to be more business-friendly:

overlay: 1.0.0
info:
  title: Partner Documentation Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/audit-log']
    remove: true
  - target: $.paths['/orders'].get
    update:
      summary: "Retrieve your order history"
      x-internal-note: null

Overlay for the Public Portal #

The public overlay is typically the most aggressive, stripping anything not meant for a general audience and possibly renaming operationIds to be more consumer-friendly for generated SDK samples:

overlay: 1.0.0
info:
  title: Public Portal Overlay
  version: 1.0.0
actions:
  - target: $.paths['/internal/admin/audit-log']
    remove: true
  - target: $.info
    update:
      description: "A simple, developer-friendly API for managing orders."

Building All Three in a Pipeline #

redocly join openapi.yaml --overlay overlays/internal.yaml   -o dist/openapi.internal.yaml
redocly join openapi.yaml --overlay overlays/partner.yaml    -o dist/openapi.partner.yaml
redocly join openapi.yaml --overlay overlays/public.yaml     -o dist/openapi.public.yaml

Each output can then be published to its own documentation portal, built with tools such as Redoc or Swagger UI, all sourced from a single spec.

Keeping Overlays Reviewable #

Because each audience-specific overlay is small and declarative, code reviewers can quickly see exactly what differs for each audience without reading a full duplicated document — a diff of a 20-line overlay is far easier to review than a diff of a 2,000-line spec.

For the underlying mechanism, see What is the OpenAPI Overlay Specification?. For a narrower version of this pattern focused on external partners only, see How can I use OpenAPI overlays to create partner-specific API subsets?.

Last updated on July 16, 2026.