How can I use OpenAPI overlays to customize documentation per environment (dev, staging, prod)?

How can I use OpenAPI overlays to customize documentation per environment (dev, staging, prod)? #

Development and staging environments often expose experimental operations, verbose debugging fields, or relaxed rate limits that should never appear in production documentation — and production may include operations not yet available in staging. Rather than hand-maintaining three near-identical OpenAPI documents, the OpenAPI Overlay Specification lets each environment be represented as a small, targeted diff against one shared base.

Environment-Specific Server URLs #

The most common environment difference is simply the servers block:

overlay: 1.0.0
info:
  title: Staging Environment Overlay
  version: 1.0.0
actions:
  - target: $.servers
    update: []

Since servers is an array, most overlay tooling requires replacing it wholesale rather than merging individual entries. A simpler and more explicit pattern is to target the document root:

overlay: 1.0.0
info:
  title: Staging Environment Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "https://staging-api.example.com/v1"
          description: "Staging environment"

Exposing Experimental Operations Only in Dev #

overlay: 1.0.0
info:
  title: Development Environment Overlay
  version: 1.0.0
actions:
  - target: $.paths['/experimental/recommendations'].get
    update:
      x-experimental: true
      description: "Experimental — available only in the dev environment. Subject to change without notice."

For staging and production overlays, this same path would simply not exist in those overlays’ base document at all, or be explicitly removed if it’s present in the shared source:

  - target: $.paths['/experimental/recommendations']
    remove: true

Adjusting Rate Limit Documentation #

Rate limits frequently differ per environment. An overlay can update the documented limits to match reality for each target:

  - target: $.paths['/orders'].get
    update:
      x-rate-limit:
        requestsPerMinute: 6000

Production overlays might document 600, while a dev overlay documents a much higher, relaxed value, keeping the docs honest for whichever environment a developer is actually testing against.

Structuring the Overlay Files #

overlays/
  env.overlay.dev.yaml
  env.overlay.staging.yaml
  env.overlay.prod.yaml

Wiring This Into a Build Matrix #

for env in dev staging prod; do
  redocly join openapi.yaml --overlay "overlays/env.overlay.$env.yaml" -o "dist/openapi.$env.yaml"
done

Each environment’s generated document can then be deployed alongside that environment’s actual API gateway, so the documentation developers see always matches the behavior of the environment they are pointed at.

Avoiding Environment Drift #

Since overlays are just YAML files under version control, environment-specific differences become visible in pull request diffs — reviewers can see exactly what’s different about staging versus production without comparing two multi-thousand-line files side by side.

See What is the OpenAPI Overlay Specification? for the foundational concepts, and How can I use OpenAPI overlays to update server URLs across environments? for a deeper look at the servers block specifically.

Last updated on July 16, 2026.