Server Variables and Multi-Environment Configuration

Server Configuration in OpenAPI

The servers section in OpenAPI defines where your API is hosted. It supports multiple environments, URL variables, and path prefixes — essential for APIs deployed across development, staging, and production environments.

Multiple Servers

servers:
  - url: https://api.example.com
    description: Production
  - url: https://staging-api.example.com
    description: Staging
  - url: http://localhost:3000
    description: Local development

Server Variables

Dynamic URL segments with variables:

servers:
  - url: https://{environment}.api.example.com/{version}
    variables:
      environment:
        default: prod
        enum:
          - prod
          - staging
          - dev
        description: Server environment
      version:
        default: v2
        enum:
          - v1
          - v2
        description: API version

This generates URLs like https://prod.api.example.com/v2 with selectable variables in Swagger UI.

Regional Servers

For multi-region deployments:

servers:
  - url: https://{region}.api.example.com
    variables:
      region:
        default: us-east
        enum:
          - us-east
          - us-west
          - eu-west
          - ap-southeast
        description: Data center region

Per-Path Server Override

Different endpoints on different servers:

paths:
  /files:
    servers:
      - url: https://upload.example.com
        description: File upload server
    post:
      summary: Upload a file

  /users:
    get:
      summary: List users
      # Uses the global server

Base Path Configuration

servers:
  - url: https://api.example.com/api/v2
    description: Production with base path

The entire path including prefix is in the server URL. Paths in the paths section are appended to the server URL.

Authentication Server

Separate auth server:

paths:
  /oauth/token:
    servers:
      - url: https://auth.example.com
    post:
      summary: Get access token

  /users:
    servers:
      - url: https://api.example.com
    get:
      summary: List users

Environment Variable Patterns

Document environment-specific behavior:

servers:
  - url: https://api.example.com
    description: |
      Production server.
      Rate limit: 1000 req/min
      Max payload: 10MB

  - url: https://sandbox.api.example.com
    description: |
      Sandbox server.
      Rate limit: 100 req/min
      Test credit cards accepted
      Data reset nightly

CORS Note

While OpenAPI does not define CORS settings, document them in server descriptions:

servers:
  - url: http://localhost:3000
    description: |
      Local dev server.
      CORS: All origins allowed