2026-10-01 · 5 min read · Rahul Chitturi
- openapi
- urls
- clients
An OpenAPI server URL can contain variables such as https://{tenant}.example.com/{version}. The document is not the URL the client calls until every brace is replaced. A generator that leaves {tenant} in the base URL, or that inserts an empty string, sends traffic to a host that does not exist.
Server variables are not path parameters. Path parameters live on an operation. Server variables live on the base URL and are shared by every operation on that server.
Require a default and keep it inside the enum
Each server variable needs a default. If enum is present, that default has to be one of the enum values. A missing default is an invalid Server Variable, even when a preview tool still renders the template.
Generators differ when a caller passes a value outside the enum. Treat the enum as the allowed set in review, and do not rely on a runtime 404 to discover that staging was never listed.
- Name every {token} in the server URL.
- Confirm each token has a default.
- Confirm the default appears in enum when enum is set.
- Keep secrets out of server variables. They ship inside the document.
Join the expanded base to the path
Paths in the document start with a slash and are appended to the expanded server URL. A server URL that already ends in a slash can produce a double slash. A server URL that is relative is resolved against the document's location, which is wrong when the spec is hosted on a docs site and the API is not.
Variable values are not escaped for you. A value that contains a slash or a question mark can change the path or the query. Prefer enums of single labels over free-form base paths.
Compare the URL the client will call
Expand the default, then expand one other enum value, and paste both into a URL parser. Diff the generated client config against the servers array in Git. The first server is the default in many tools, so a later production entry may never be selected.
Use Flashman's YAML/JSON converter for the document, the URL tool for the expanded base and path, the JSON formatter for generated client config, and diff for the spec before and after bundling.