Addressed metadata documentation cleanup from #589 #812
Conversation
|
In the OpenAPI object the Also the description of the Host Object seems to have got stuck in the middle of the description of the Info Object. |
|
I prefer and I think "server" (as in "API server" / "service") is a better term here than host, as |
|
@darrelmiller i will fix that. |
|
Need to add a new doc that discusses migration guidelines and expectations from tooling vendors in regards to being compatible between minor versions. |
| The following shows how multiple hosts can be described in the host object array | ||
|
|
||
| ```yaml | ||
| servers: |
There was a problem hiding this comment.
alternatives for servers: instances … ?
|
the terms |
| enum: | ||
| - https | ||
| - http | ||
| default: https |
There was a problem hiding this comment.
default currently applies to optional parameters and represents the server-assumed default, like the number of results in a page or an offset. By applying it to a required element, we confuse an already tricky aspect of a spec. An alternative could be example.
| servers: | ||
| - url: {scheme}://{host}:{port}/{basePath} | ||
| description: The production API server | ||
| templates: |
There was a problem hiding this comment.
As discussed, introducing templates when other path templates use parameters seems less elegant, but I don't have a better alternative to supply at this time.
|
@webron to add documentation about what happens when the |
Addressed metadata documentation cleanup from OAI#589
See #589 (comment)