added host section #646
added host section #646
Conversation
|
Moved from #640. @OAI/tdc please approve or reject |
| <a name="oasHost"></a>host | `string` | The host (name or ip) serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. If the `host` is not included, the host serving the documentation is to be used (including the port). The `host` does not support [path templating](#pathTemplating). | ||
| <a name="oasBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#oasHost). If it is not included, the API is served directly under the `host`. The value MUST start with a leading slash (`/`). The `basePath` does not support [path templating](#pathTemplating). | ||
| <a name="oasSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself. | ||
| <a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner. |
|
👍 This should also also affect the same fields as described at https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/versions/3.0.md#operationObject. |
|
👍 |
|
LGTM |
|
The biggest issue I see with this:
IMO in Swagger 2.0, 👎 as it stands |
|
@jasonh-n-austin Please take a look at #641 it should addresses all your concerns.
I think best ID is URL generated from this element, so user can choose based on it.
I strongly disagree, it's very useful for public APIs like Instagram, Facebook, etc.
In that case you can strip based on some kind of vendor extension, e.g. |
|
I didn't realize the intent of the hosts array was to enable the identification of different environments. I thought it was for enumerating identical service instances. Therefore it wouldn't matter which host you chose, the effect would be the same. This would allow the client to pick a closest server, or round robin requests as well as pick the scheme they want to use. Making OpenAPI responsible for identifying multiple different environments seems like a fairly significant increase in responsibility and certainly opens the questions about default environment and which hosts are equivalent and which are not. Are we sure we want to go there? The original issue was not trying to solve that problem. |
|
@darrelmiller - that's a fair point. However, that's not really the intent. I think that's the difference between use and abuse. The spec shouldn't say it should be used for that or intended to be used for that, but users may end up doing so - we can't stop it. I agree the goal here is just to be able to fine-tune the host definition is which is a bit limited today. |
|
@jasonh-n-austin my view is that the hosts object is an ordered list, we can make it clear that there is an implicit order of precedence. Given that and the other votes, I'm merging this and we can always revisit. |
|
can someone just give an example of how they have implemented the multiple swagger host? I am a bit new to swagger |
|
@sidhantdas007 this can only be done natively in OpenAPI 3.0 (the successor to the Swagger specification). A simple example: https://github.com/APIs-guru/openapi-directory/blob/openapi3.0.0/APIs/bbci.co.uk/1.0/openapi.yaml#L1-L5 You can mention additional |
add host section [Manually ported merge] Co-authored-by: Tony Tam <[email protected]>
Fixes issue #214