Follow-up to #7606, where I said I'd open this separately if multi-host specs are in scope.
First, a correction to the numbers I posted there. I counted specs where path-level or operation-level servers is present (57 and 33). That's the wrong measure — most overrides restate the root server, and ignoring those is harmless. Counting only overrides whose URL differs from the root:
| spec |
present |
differs from root |
| Twilio (api) |
121 |
0 |
| Linode |
89 |
2 |
| Box |
14 |
14 |
Twilio was the example I led with and it's redundant — all 121 path items declare https://api.twilio.com, which is already the root.
What's left
spec.py::_resolve_base_url reads servers[0] at the document root and that becomes the single base_url for every command. OpenAPI allows servers on a Path Item and an Operation, most specific winning. Neither is read, so an operation on a different host is dispatched to the root host.
Box, root https://api.box.com/2.0:
GET /authorize -> https://account.box.com/api/oauth2
POST /files/content -> https://upload.box.com/api/2.0
POST /files/upload_sessions -> https://upload.box.com/api/2.0
DELETE /files/upload_sessions/{upload_session_id} -> https://upload.box.com/api/2.0
Uploads are only served by upload.box.com. Those commands go to api.box.com and fail at dispatch. Generation reports nothing.
Linode is the same shape, smaller: two v4beta operations under a v4 root.
Question
Are multi-host specs in scope for the codegen?
A per-command base URL changes the spec document shape and how dispatch resolves a target, and it lands differently on --generate-extension, since a generated provider package has no equivalent of --base-url. If that's not a direction you want, say so and I'll close this — Box-style upload hosts are arguably a per-provider concern.
If it is in scope, the cheap version is generation warning about commands whose declared host it's ignoring, which needs no shape change. Honoring the override properly is the larger one. I'll write either.
Checked against v5. Specs re-fetched from APIs.guru and verified individually.
Follow-up to #7606, where I said I'd open this separately if multi-host specs are in scope.
First, a correction to the numbers I posted there. I counted specs where path-level or operation-level
serversis present (57 and 33). That's the wrong measure — most overrides restate the root server, and ignoring those is harmless. Counting only overrides whose URL differs from the root:Twilio was the example I led with and it's redundant — all 121 path items declare
https://api.twilio.com, which is already the root.What's left
spec.py::_resolve_base_urlreadsservers[0]at the document root and that becomes the singlebase_urlfor every command. OpenAPI allowsserverson a Path Item and an Operation, most specific winning. Neither is read, so an operation on a different host is dispatched to the root host.Box, root
https://api.box.com/2.0:Uploads are only served by
upload.box.com. Those commands go toapi.box.comand fail at dispatch. Generation reports nothing.Linode is the same shape, smaller: two
v4betaoperations under av4root.Question
Are multi-host specs in scope for the codegen?
A per-command base URL changes the spec document shape and how dispatch resolves a target, and it lands differently on
--generate-extension, since a generated provider package has no equivalent of--base-url. If that's not a direction you want, say so and I'll close this — Box-style upload hosts are arguably a per-provider concern.If it is in scope, the cheap version is generation warning about commands whose declared host it's ignoring, which needs no shape change. Honoring the override properly is the larger one. I'll write either.
Checked against
v5. Specs re-fetched from APIs.guru and verified individually.