Merge pull request OAI#812 from OAI/issue-589

Addressed metadata documentation cleanup from OAI#589

Author: fehguy

versions/3.0.md

@@ -125,9 +125,9 @@ It combines what previously was the Resource Listing and API Declaration (versio
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
+<a name="oasVersion"></a>openapi | [OpenAPI Version String](#oasVersion) | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version. The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed.
-<a name="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
+<a name="oasHosts"></a>servers | [[Server Object](#serverObject)] | An optional array of Server Objects which provide connectivity information to a target server.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
 <a name="oasComponents"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
 <a name="oasSecurity"></a>security | [[Security Requirement Object](#securityRequirementObject)] | A declaration of which security schemes are applied for the API as a whole. The list of values describes alternative security schemes that can be used (that is, there is a logical OR between the security requirements). Individual operations can override this definition.
@@ -136,6 +136,15 @@ Field Name | Type | Description
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
+#### <a name="oasVersion"></a>OpenAPI Version String
+
+The version string signifies the version of the OpenAPI Specification that the document complies to.  The format for this string _must_ be `major`.`minor`.`patch`.  The `patch` _may_ be suffixed by a hyphen and extra alphanumeric characters.
+
+A `major`.`minor` shall be used to designate the OpenAPI Specification version, and will be considered compatible with the OpenAPI Specification specified by that `major`.`minor` version.  The patch version will not be considered by tooling, making no distinction between `3.0.0` and `3.0.1`.
+
+In subsequent versions of the OpenAPI Specification, care will be given such that increments of the `minor` version should not interfere with operations of tooling developed to a lower minor version.  Thus a hypothetical `3.1.0` specification should be usable with tooling designed for `3.0.0`.
+
+
 #### <a name="infoObject"></a>Info Object
 
 The object provides metadata about the API.
@@ -188,18 +197,6 @@ license:
 version: 1.0.1
 ```
 
-#### <a name="hostObject"></a>Host Object
-
-An object representing a Host.
-
-##### Fixed Fields
-
-Field Name | Type | Description
----|:---:|---
-<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="oasScheme"></a>scheme | `string` | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. If the `scheme` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
-
 #### <a name="contactObject"></a>Contact Object
 
 Contact information for the exposed API.
@@ -257,6 +254,78 @@ name: Apache 2.0
 url: http://www.apache.org/licenses/LICENSE-2.0.html
 ```
 
+#### <a name="serverObject"></a>Server Object
+
+An object representing a Server.
+
+##### Fixed Fields
+
+Field Name | Type | Description
+---|:---:|---
+<a name="serverUrlTemplate"></a>server URL template | `string` | A URL to the target host.  This URL supports template variables and may be relative, to indicate that the host location is relative to the location where the OpenAPI Specification is being served.  Templates are _optional_ and specified by the [#hostTemplateParameter] syntax.  Template substitutions will be made when a variable is named in `{`brackets`}`.
+<a name="hostDescription"></a>host description | `string` | An optional string describing the host designated by the URL.
+<a name="hostTemplates"></a>templates | [Templates Object](#hostTemplatesObject) | An object holding templates for substitution in the URL template
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+##### Server Object Example
+
+The following shows how multiple hosts can be described in the Server Object array
+
+```yaml
+servers:
+- url: https://development.gigantic-server.com/v1
+  description: Development server
+- url: https://staging.gigantic-server.com/v1
+  description: Staging server
+- url: https://api.gigantic-server.com/v1
+  description: Production server
+```
+
+The following shows how templates an be used for a server configuration
+
+```yaml
+servers:
+- url: https://{username}.gigantic-server.com:{port}/{basePath}
+  description: The production API server
+  templates:
+    username:
+      # note! no enum here means it is an open value
+      default: demo
+      description: this value is assigned by the service provider, in this example `gigantic-server.com`
+    port:
+      enum:
+        - 8443
+        - 443
+      default: 8443
+    basePath:
+      # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
+      default: v2
+```
+
+#### <a name="hostTemplatesObject"></a>Host Templates Object
+
+##### Patterned Fields
+
+Field Pattern | Type | Description
+---|:---:|---
+<a name="variable"></a> [variable name] | [Host Template Parameter](#hostTemplateParameter) | A parameter to be used for substitution in the URL template.
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+
+#### <a name="hostTemplateParameter"></a>Host Template
+
+An object representing a Host URL template
+
+Field Name | Type | Description
+---|:---:|---
+enum | [Possible Values] | An enumeration of primitive type values to be used if the substitution options are from a limited set.
+default | [Default Value] |  **Required.** The default value to use for substitution if an alternate value is not specified, and will be sent if an alternative value is _not_ supplied.
+description | `string` | An optional description for the template parameter
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
 #### <a name="componentsObject"></a>Components Object
 
 Holds a set of schemas for different aspects of the OAS.
@@ -1950,6 +2019,9 @@ The following properties are taken from the JSON Schema definition but their def
 Their definition is the same as the one from JSON Schema, only where the original definition references the JSON Schema definition, the [Schema Object](#schemaObject) definition is used instead.
 - items
 - allOf
+- oneOf
+- anyOf
+- not
 - properties
 - additionalProperties