OpenAPI servers and server variables: local, staging, production, regions, and per-tenant hosts from one spec

Multiple servers with different URLs can be defined within a single OpenAPI specification to accommodate various environments like local development, staging, production, specific regions, and per-tenant hosts. This approach allows for a single document to describe all these scenarios, eliminating the need to fork the spec. The servers array replaces the OpenAPI 2.0 host, basePath, and schemes fields with a list of base URLs.

Each operation path is resolved relative to the selected server, enabling the API to be accessed using the appropriate URL based on the context. For instance, a GET request to /users would generate the correct URL, such as https://api.example.com/v1/users in production or http://localhost:4010/v1/users for the local mock server. It is recommended to place the production server first in the list, but always include the local mock server to ensure generated clients and mock servers align on the URL structure.

Server variables can be defined for regions and tenants, allowing the host to vary based on a limited set of values. These variables are enumerated in the servers array and used to generate appropriate URLs. Clients and documentation renderers can present these variables as dropdown menus or input fields. When defining variables, use an enum for known and small sets (like regions or environments) and a free-text variable with a default value for values known only to the customer. Variables can be included in the host, path, or both, but should be avoided in query strings.

Relative servers and same-origin documentation are useful when the API documentation and the API itself share the same origin, such as when docs are served from the same domain. In such cases, using a relative server URL (/v1) ensures that calls resolve to the correct base path, such as https://app.example.com/v1/. However, this approach may not work well in environments where the origin is assigned at deploy time.

Operation- and path-level servers can also be defined to model endpoints served from different hosts, like file services or webhook receivers. However, this should be used sparingly, as it can lead to clients configuring multiple hosts and confusion in documentation. When necessary, maintain a clear and consistent server prefix, avoid trailing slashes in server URLs, and explicitly include the scheme to prevent issues with URL resolution.