added hosts setting

Author: fehguy

versions/3.0.md

@@ -127,7 +127,7 @@ Field Name | Type | Description
 ---|:---:|---
 <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>hosts | [Host Object](#hostObject) | An array of Host objects which provide connectivity information to a target host.
 <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.
@@ -205,9 +205,73 @@ An object representing a Host.
 
 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="hostUrlTemplate"></a>host 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). 
+
+##### Host Object Example
+
+The following shows how multiple hosts can be described in the host 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 host configuration
+
+```yaml
+servers:
+- url: {scheme}://{host}:{port}/{basePath}
+  description: The production API server
+  templates:
+    scheme:
+      enum:
+        - https
+        - http
+      default: https
+    host:
+      enum:
+        - na1.gigantic-server.com
+        - na2.gigantic-server.com
+    port:
+      enum:
+        - 8443
+        - 443
+      default: 8443
+    basePath:
+      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
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
 
 #### <a name="contactObject"></a>Contact Object