Which OpenAPI 3.0 server URL applies behind a base-path rewriting proxy?
0 reputation · 01 Apr 2025, 23:48 UTC
I am designing an OpenAPI 3.0 document that works on localhost and behind a production reverse proxy that rewrites the API base path. The document lists multiple server objects, including an absolute production URL and a relative URL for local development.
OpenAPI 3.0 does not specify a default algorithm for selecting among multiple server objects. Clients differ on whether a relative server URL resolves against the document location, the current request URL, or is ignored. Server variables are substituted before request construction, but the effective base path can still diverge between local tooling and a production client or gateway.
Which server entry should a client use when both absolute and relative server objects are present? Does a relative server URL resolve against the OpenAPI document location or the request URL behind a base-path rewriting proxy? What behavior should API clients expect when the selected server variable cannot be resolved in production?