Switch API base URLs across environments with OpenAPI 3.0 server variables

Hardcoded base URLs force duplicate API definitions

If your OpenAPI document hardcodes https://api.example.com/v1, every environment needs its own copy of the file or a find-and-replace step before publishing. OpenAPI 3.0 solves this with the top-level servers array and server variables: one document can declare development, staging, and production base URLs, and clients or UI tools pick the active one at runtime or generation time.

Useful takeaway: define server URLs as templates with named variables, supply defaults and allowed values, then override the variable per environment instead of editing every path.

How OpenAPI 3.0 server variables work

The servers array holds server objects. Each object has a url string and an optional variables map. Curly braces in the URL mark substitution points, for example {environment}. The variables map assigns each name a default and an optional enum of allowed values. Operations inherit the selected server unless a path or operation object declares its own servers array.

Important terms: a server variable is a named placeholder in a server URL. Swagger UI is the browser-based interface that renders an OpenAPI document and usually offers a server selector. OpenAPI Generator produces client code from the document.

Worked configuration

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
servers:
  - url: https://{environment}.api.example.com/{basePath}
    variables:
      environment:
        default: prod
        enum:
          - dev
          - staging
          - prod
      basePath:
        default: v1
        enum:
          - v1
          - v2
paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: OK

With no override, tools resolve https://prod.api.example.com/v1. To target staging, a client or UI sets environment to staging, producing https://staging.api.example.com/v1.

A path-level server declaration replaces the whole inherited array; it does not merge:

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

Validate and verify the document

Run these checks in the repository root where openapi.yaml lives. You need read permission on the file; no administrative privileges are required.

Lint the OpenAPI schema

spectral lint openapi.yaml --ruleset spectral:oas3

Expected result: no errors related to server structure or variable substitution. Risk: some linters validate syntax but do not confirm that downstream tooling honors enum values.

Inspect Swagger UI server selection

Load the document in Swagger UI and open the server dropdown, usually at the top of the page. Changing the selected server should update the URL shown next to Try it out for each operation. If the dropdown shows only the default, the UI version may not expose server variables.

Generate a client stub

openapi-generator generate -i openapi.yaml -g typescript-axios -o ./client

Inspect the generated client configuration. The base URL should be constructible from the document defaults and overridable when the client is instantiated. If the generator hardcodes one URL, server variables are not portable to that client.

Limits and common mistakes

• Server variables substitute only inside the servers[].url string. They cannot replace path parameters, header values, or query strings.
• Relative server URLs, such as /api/v1, resolve against the location of the OpenAPI document, which can surprise teams expecting absolute addresses.
• A servers entry at the path or operation level replaces the entire inherited array. It does not append to or merge with the top-level list.
• Tooling varies on enum enforcement. Some clients silently fall back to the default when given an unlisted value instead of rejecting it.
• Never put secrets, such as API keys or credentials, in a server URL. Generated clients may log, cache, or expose the resolved address.
• Changing a default after client code is generated can break runtime calls if the client baked in the resolved URL instead of reading it from the document.

Rollback

Because this change edits a text file, rollback means reverting the openapi.yaml commit and regenerating any affected client stubs. There is no runtime state to undo.

Version assumptions

This guidance applies to OpenAPI 3.0.x. Swagger UI and OpenAPI Generator versions differ in how completely they support server variables, so verify behavior for the exact toolchain versions in use.