added changes to include host, basePath, schemes #604
Conversation
|
@OAI/tdc Please review and comment |
| @@ -318,6 +318,9 @@ Field Name | Type | Description | |||
| <a name="pathItemOptions"></a>options | [Operation Object](#operationObject) | A definition of a OPTIONS operation on this path. | |||
| <a name="pathItemHead"></a>head | [Operation Object](#operationObject) | A definition of a HEAD operation on this path. | |||
| <a name="pathItemPatch"></a>patch | [Operation Object](#operationObject) | A definition of a PATCH operation on this path. | |||
| <a name="pathItemHost"></a>host | `string` | The host (name or ip) serving the path. This optional value will override the top-level [host](#oasHost) if present. 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="pathItemBasePath"></a>basePath | `string` | The base path on which the API is served, which is relative to the [`host`](#pathItemHost). This optional value will override the top-level [basePath](#oasBasePath) if present. 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). | |||
There was a problem hiding this comment.
I think the current third sentence of this paragraph should be something like this:
If it is not included, the top level
basePathis used, if that is also not included, the API is served directly under thehost.
Similar changes would apply to pathItemHost, pathItemSchemes, and the operation level overrides.
There was a problem hiding this comment.
The first sentence in this paragraph should maybe not say "on which this API is served", but "on which this path is served"?
(Analogously for operation/basePath.)
|
It might be useful to also add a sentence to each of the descriptions of the top level |
| @@ -422,6 +425,9 @@ Field Name | Type | Description | |||
| <a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol for the operation. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. The value overrides the OpenAPI Object [`schemes`](#oasSchemes) definition. | |||
| <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`. | |||
| <a name="operationSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for this operation. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). This definition overrides any declared top-level [`security`](#oasSecurity). To remove a top-level security declaration, an empty array can be used. | |||
| <a name="operationHost"></a>host | `string` | The host (name or ip) serving the path. This optional value will override the top-level [host](#oasHost) or path item-level [host](#pathItemHost). if present. 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). | |||
There was a problem hiding this comment.
Should "serving the path" be "handling the operation" or something "operation" specific? Might also make sense to mention the order in which things are overridden in the order they are checked. So instead of "the top-level or path item-level" it might make sense to say _"the path item-level and the top-level".
|
LGTM with nits |
|
Thanks for the comments. We'll do wordsmithing in one fell swoop as things move forward. Any other input, @OAI/tdc ? Otherwise I'll merge. |
Please see discussion in #562. This change documents proposed changes to allow
host,basePath, andschemesto optionally be specified in PathItem and Operation objects.