Merge remote-tracking branch 'refs/remotes/origin/OpenAPI.next' into dm/componentsreview

Author: darrelmiller

CONTRIBUTORS.md

@@ -2,5 +2,6 @@
 * Jason Harmon [@jharmn](https://github.com/jharmn)
 * Jeremy Whitlock [@whitlockjc](https://github.com/whitlockjc)
 * Marsh Gardiner [@earth2marsh](https://github.com/earth2marsh)
+* Rob Dolin [@RobDolinMS](https://github.com/robdolinms)
 * Ron Ratovsky [@webron](https://github.com/webron)
 * Tony Tam [@fehguy](https://github.com/fehguy)

versions/3.0.md

@@ -14,6 +14,61 @@ The OpenAPI Specification defines a set of files required to describe such an AP
 These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages.
 Additional utilities can also take advantage of the resulting files, such as testing tools.
 
+## Table of Contents
+<!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
+
+- [OpenAPI Specification](#openapi-specification)
+- [Introduction](#introduction)
+- [Table of Contents](#table-of-contents)
+- [Revision History](#revision-history)
+- [Definitions](#definitions)
+- [Specification](#specification)
+	- [Format](#format)
+	- [File Structure](#file-structure)
+	- [Data Types](#data-types)
+	- [Schema](#schema)
+		- [OpenAPI Object](#openapi-object)
+		- [Info Object](#info-object)
+		- [Host Object](#host-object)
+		- [Contact Object](#contact-object)
+		- [License Object](#license-object)
+		- [Components Object](#components-object)
+		- [Paths Object](#paths-object)
+		- [Path Item Object](#path-item-object)
+		- [Operation Object](#operation-object)
+		- [External Documentation Object](#external-documentation-object)
+		- [Parameter Object](#parameter-object)
+		- [Request Body Object](#request-body-object)
+		- [Content Object](#content-object)
+		- [Content Type Object](#content-type-object)
+		- [Items Object](#items-object)
+		- [Responses Object](#responses-object)
+		- [Response Object](#response-object)
+		- [Headers Object](#headers-object)
+		- [Examples Object](#examples-object)
+		- [Links Object](#links-object)
+		- [Link Object](#link-object)
+		- [Variable substitution](#variable-substitution)
+		- [Link Parameters](#link-parameters)
+		- [Header Object](#header-object)
+		- [Tag Object](#tag-object)
+		- [Examples Object](#examples-object)
+		- [Reference Object](#reference-object)
+		- [Schema Object](#schema-object)
+		- [XML Object](#xml-object)
+		- [Definitions Object](#definitions-object)
+		- [Parameters Definitions Object](#parameters-definitions-object)
+		- [Responses Definitions Object](#responses-definitions-object)
+		- [Security Definitions Object](#security-definitions-object)
+		- [Security Scheme Object](#security-scheme-object)
+		- [Scopes Object](#scopes-object)
+		- [Security Requirement Object](#security-requirement-object)
+	- [Specification Extensions](#specification-extensions)
+	- [Security Filtering](#security-filtering)
+	
+
+<!-- /TOC -->
+
 ## Revision History
 
 Version | Date | Notes
@@ -262,7 +317,7 @@ An object representing a Server.
 
 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="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 [Host Template Parameter](#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
 
@@ -351,14 +406,14 @@ This namespacing mechanism is simply a naming convention and this specification
 #### <a name="pathsObject"></a>Paths Object
 
 Holds the relative paths to the individual endpoints.
-The path is appended to the [`basePath`](#oasBasePath) in order to construct the full URL.
-The Paths may be empty, due to [ACL constraints](#securityFiltering).
+The path is appended to the [`Server Object`](#serverObject) in order to construct
+the full URL.  The Paths may be empty, due to [ACL constraints](#securityFiltering).
 
 ##### Patterned Fields
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is appended to the [`basePath`](#oasBasePath) in order to construct the full URL. [Path templating](#pathTemplating) is allowed.
+<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | A relative path to an individual endpoint. The field name MUST begin with a slash. The path is appended to the [`Server Object`](#serverObject) in order to construct the full URL. [Path templating](#pathTemplating) is allowed.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -424,9 +479,8 @@ 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). 
-<a name="pathItemSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
+<a name="pathItemTrace"></a>trace | [Operation Object](#operationObject) | A definition of a TRACE operation on this path.
+<a name="pathItemServer"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service all operations in this path.  
 <a name="pathItemParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [___location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters). 
 
 
@@ -533,9 +587,7 @@ 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).
-<a name="operationBasePath"></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) or path item-level [basePath](#oasPathItemBasePath) 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). 
-<a name="operationSchemes"></a>schemes | [`string`] | The transfer protocol of the API. Values MUST be from the list: `"http"`, `"https"`, `"ws"`, `"wss"`. This optional value will override the top-level [schemes](#oasSchemes) or path-item level [schemes](#pathItemSchemes) if present. If the `schemes` is not included, the default scheme to be used is the one used to access the OpenAPI definition itself.
+<a name="operationItemServer"></a>servers | [Server Object](#serverObject) | An alternative `server` array to service this operation. If an alternative `server` object is specified at the Path Item Object or Root level, it will be overridden by this value.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -607,7 +659,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 tags:
 - pet
 summary: Updates a pet in the store with form data
-description: ""
+description: ''
 operationId: updatePetWithForm
 parameters:
 - name: petId