Server variable resolution diverges between local and production builds

Answer

When a server variable is omitted in the spec, most OpenAPI generators (e.g., OpenAPI Generator v6.x, Swagger Codegen v3) fallback to the first server object in the servers array and substitute any undefined variables with that server’s default values. If the first server does not provide a default for a missing variable, the placeholder literal (e.g., {basePath}) is left unchanged, which can produce malformed URLs.

Confirmed facts

• The OpenAPI Specification does not prescribe a universal fallback; each generator implements its own rule.
• Generator versions prior to 5.x may treat missing variables as errors and abort generation.
• Security schemes bound to a specific server are not automatically copied to a fallback server.

Likely explanation of the divergence

The difference between local and production builds arises because the generator picks the first server entry as the fallback. If the first entry is the production server, local builds will inherit its host (or placeholder) unless a localhost‑specific server appears earlier in the array.

Steps to declare a portable fallback (no hard‑coded hosts)

1. Add a server that defines default values for every variable** you intend to use, e.g.:

servers:
  - url: https://{environment}.example.com/{basePath}
    variables:
      environment:
        default: "prod"
      basePath:
        default: "api"
  - url: http://localhost:{port}/{basePath}
    variables:
      port:
        default: "8080"
      basePath:
        default: "api"

1. Ensure the localhost server appears first** in the array if you want local builds to resolve to http://localhost:{port} by fallback.
2. If security schemes are tied to a server, duplicate the same security block on both server objects so the fallback retains authentication.

Validation steps to confirm correct base‑URL generation

1. Generate the client code with your chosen generator version.
2. Instantiate the API client and inspect the resolved base path/configuration (e.g., Configuration.basePath or apiClient.getBasePath()).
3. Run a unit test that asserts the base URL equals http://localhost:{port} when the localhost server is selected and equals the production domain when the production server is selected.
4. Optionally, add a request interceptor or logger to the generated client and verify that actual outbound requests match the expected base URL in each environment.

Missing diagnostic detail

To confirm whether the fallback‑to‑first‑server rule applies in your case, please specify: What version of the OpenAPI generator are you using? (Versions <5.x may require an upgrade or explicit defaults to avoid generation errors.)