How can I use OpenAPI overlays to update server URLs across environments?

How can I use OpenAPI overlays to update server URLs across environments? #

The servers block in an OpenAPI document tells tooling — and developers — where to actually send requests. It’s also one of the most environment-specific parts of the entire document: local development might point at http://localhost:3000, staging at a dedicated staging domain, and production at the live API host, sometimes with additional regional variants. The OpenAPI Overlay Specification provides a clean way to swap this block per environment without maintaining separate copies of the whole document.

Why `servers` Deserves Special Treatment #

Unlike most overlay targets, servers is an array, and the update action performs a merge rather than a smart per-item patch in most implementations. In practice, this means the safest and most predictable approach is to replace the entire array rather than trying to patch a single entry within it.

Overlay for Local Development #

overlay: 1.0.0
info:
  title: Local Development Servers Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "http://localhost:3000"
          description: "Local development server"

Overlay for Staging #

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

Overlay for Multi-Region Production #

Production may need multiple regional endpoints listed simultaneously:

overlay: 1.0.0
info:
  title: Production Multi-Region Servers Overlay
  version: 1.0.0
actions:
  - target: $
    update:
      servers:
        - url: "https://api.us.example.com/v1"
          description: "US production region"
        - url: "https://api.eu.example.com/v1"
          description: "EU production region"
        - url: "https://api.apac.example.com/v1"
          description: "APAC production region"

Using Server Variables Instead of Multiple Overlays #

If your tooling and generators support OpenAPI’s native server variables, a single overlay can parameterize the environment instead of maintaining one overlay per environment:

  - target: $
    update:
      servers:
        - url: "https://{environment}-api.example.com/v1"
          variables:
            environment:
              default: "staging"
              enum: ["dev", "staging", "api"]

This trades some overlay simplicity for a more flexible single output, and works well when the same documentation portal needs to let a developer pick their target environment interactively.

Wiring This Into the Build #

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

Validating the Result #

Because a mistake in the servers overlay can silently point an entire generated SDK at the wrong host, add an automated check after applying the overlay that asserts the expected URL appears in the output:

grep -q "https://api.us.example.com/v1" dist/openapi.production.yaml || (echo "Production server URL missing!" && exit 1)

See What is the OpenAPI Overlay Specification? and How can I use OpenAPI overlays to customize documentation per environment (dev/staging/prod)? for the broader environment-specific documentation pattern.

Last updated on July 16, 2026.