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