Client-Side Resolution of Relative Paths
When relative paths (e.g., /v1) are used in the servers object of an OpenAPI Specification (OAS), the client-side request resolution relies entirely on the origin of the document. If the OAS documentation UI is hosted on docs.example.com but the API Gateway is hosted on api.example.com, a relative path will resolve to docs.example.com/v1, resulting in a 404 or a CORS error.
Relative URLs are only portable when the API Gateway and the documentation UI share the same host and port. In a decoupled architecture where the Gateway is on a separate domain, relative paths break the request chain because the browser cannot automatically infer a different domain for the API target.
OAS Prioritization and Runtime Overrides
The OAS 3.0.x specification does not provide a built-in mechanism to prioritize server definitions based on runtime infrastructure overrides. The servers array is a static list of targets. The responsibility for selection falls into two categories:
- UI-Level Selection: Most OAS renderers (like Swagger UI or Redoc) provide a dropdown menu allowing the user to manually select which server URL to use.
- Client-Side Logic: Generated clients typically treat the first entry in the
servers array as the default, but allow the base URL to be overridden programmatically during client instantiation.
Recommended Implementation for Multi-Environment Portability
To maintain portability without hardcoding environment-specific IPs, use a combination of Server Variables and Environment Injection:
- Define Server Variables: Use the
variables object within the servers array to parameterize the host.
servers:
- url: https://{environment}.example.com/v1
variables:
environment:
default: api
enum: [local, staging, api]
- Inject via Build Pipeline: For production deployments, use a CI/CD step to replace the
default value or the entire servers block with the environment-specific absolute URL.
- Gateway Proxying: If relative URLs are a hard requirement, configure the documentation host to proxy
/v1 requests to the API Gateway domain at the infrastructure level (e.g., via Nginx or an Ingress Controller).
Verification Steps
To verify resolution behavior, perform the following checks in the browser developer tools:
- Network Tab: Trigger a request from the UI and verify the Request URL. If it matches the documentation domain instead of the gateway domain, the relative path is resolving incorrectly.
- CORS Headers: Ensure the API Gateway includes
Access-Control-Allow-Origin headers that explicitly permit the domain hosting the OAS UI.
Diagnostic Detail Needed: Are you using a specific OAS UI renderer (e.g., Swagger UI, Redoc) or a custom-generated SDK? The method for overriding the base URL varies significantly between a browser-based UI and a compiled client library.
openapi