Swagger UI server URL resolution failure behind reverse proxies

Answer

Swagger UI treats relative URLs in the servers array as relative to the browser window’s origin (window.location.origin). It does not consult reverse‑proxy headers such as X-Forwarded-Host or X-Forwarded-Proto; those are only meaningful to the backend server.

Confirmed facts

• The servers array is read from the OpenAPI document (JSON/YAML) that Swagger UI loads.
• If a server entry is a relative path (e.g., /api), the UI prepends window.location.origin to form the absolute request URL.
• If a server entry is an absolute URL (including scheme, host, port, and optional path), it is used unchanged.
• Reverse‑proxy headers are processed by the API server, not by the Swagger UI client.

Likely explanation

When the UI is served from a different origin than the API, a relative server entry resolves to the UI’s origin, causing requests to be sent to the wrong host (often resulting in 404 or CORS errors). The UI has no way to infer the external host that the reverse proxy presents to clients.

Steps to achieve consistent routing

1. Open the Network tab, locate the request for swagger.json (or the OpenAPI endpoint) and verify the servers array content.
2. If the array contains only relative paths, replace them with absolute URLs that match the public host exposed by the reverse proxy (e.g., https://api.example.com).
3. To keep the specification portable, configure the backend to serve a dynamic OpenAPI document where the servers array is populated from an environment variable or from request headers (e.g., using X-Forwarded-Host on the server side).
4. Reload Swagger UI and check the “Try it out” request URL in the Network tab; it should now point to the correct public host.
5. Ensure CORS is enabled on the API for the UI’s origin if they remain separate.

Missing diagnostic detail

Is the OpenAPI specification (swagger.json) being served from the same origin as the Swagger UI, or is it proxied through the same reverse‑proxy layer? Knowing this determines whether you need to adjust the UI’s base URL or modify the backend’s dynamic server generation.