2026-10-01 · 7 min read
- openapi
- urls
- clients
OpenAPI server objects tell a client where an API lives. The url field may contain named variables in braces. Those variables are replaced before any operation path is appended. A document that still shows braces, or that substitutes an empty string, is not ready to call.
The Server Variable object requires a default. An optional enum lists the values a client may use, and the default must be one of them. Description text does not constrain the value.
Expand the template before you review the host
List every brace pair in the server URL and find a variable of that name. A brace with no variable, or a variable that is never referenced, is a defect. Substitute the default first so reviewers see the URL that generators will emit when the caller passes nothing.
Then substitute each other enum value. Read the host, the path, and the query as separate parts. Server variables are shared by every operation on that server. They are not a place to encode a single operation's id.
- Give every variable a default.
- Keep the default inside enum when enum is present.
- Use short labels in enums, not full URLs.
- Leave credentials and private hosts out of the published document.
Resolve relative servers against the right base
A server URL without a scheme is relative to the OpenAPI document's location. That is useful when the spec and the API are deployed together. It is wrong when the spec is served from a documentation host, a raw Git URL, or a bundler preview.
Prefer an absolute server URL in documents that will be downloaded and generated from CI. If you keep a relative URL, test it from the URL where consumers fetch the spec, not from the path in the Git repository.
Append operation paths without surprising slashes
Operation paths start with a slash and are appended to the expanded server URL. They are not resolved the way a browser resolves a relative link against a directory. A server URL of https://api.example.com/v1/ plus a path of /users can become a URL with a double slash, depending on the generator.
Pick one convention and test it. Either the server URL has no trailing slash, or the generator trims one side before joining. Do not put a query string in the server URL and another on the operation unless you have checked which one survives.
Stop values from rewriting the URL
Substituted values are not percent-encoded by the spec's server-variable rules. A tenant value that contains a slash, a question mark, or a hash can escape the path segment you intended. Enums of fixed labels avoid that class of bug.
Multiple server entries are an ordered list. Many generators call the first one and hide the rest behind a configuration flag. Put the URL you want by default first, and diff the generated client so a docs server is not the one that shipped.
Check the expanded URL in Flashman
Use the YAML/JSON converter on the OpenAPI document, the URL tool on each expanded server plus a representative path, the JSON formatter on the generated client config, and diff on the document before and after bundling.
Review the default expansion, one non-default enum value, a relative server fetched from the published spec URL, and a path join. The host in the client should be the host you meant to call.