Merge branch 'jasonh-n-austin-OpenAPI.next' into OpenAPI.next

fehguy · fehguy · commit baf1061ceacb · 2016-06-06T09:52:17.000-07:00
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -346,7 +346,7 @@ Field Name | Type | Description
 <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="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). There can be one "body" parameter at most.
+<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). 
 
 ##### Patterned Fields
 
@@ -445,7 +445,8 @@ Field Name | Type | Description
 <a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
 <a name="operationConsumes"></a>consumes | [`string`] | A list of MIME types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
 <a name="operationProduces"></a>produces | [`string`] | A list of MIME types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
-<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. 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). There can be one "body" parameter at most.
+<a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. 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).
+<a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation. 
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <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`.
@@ -595,25 +596,24 @@ Describes a single operation parameter.
 
 A unique parameter is defined by a combination of a [name](#parameterName) and [___location](#parameterIn).
 
-There are six possible parameter types.
+There are five possible parameter types.
 * Path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
 * Query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
 * Header - Custom headers that are expected as part of the request.
-* Body - The payload that's appended to the HTTP request. Since there can only be one payload, there can only be *one* body parameter. The name of the body parameter has no effect on the parameter itself and is used for documentation purposes only. Since Form parameters are also in the payload, body and form parameters cannot exist together for the same operation.
 * Form - Used to describe the payload of an HTTP request when either `application/x-www-form-urlencoded`, `multipart/form-data` or both are used as the content type of the request (in the OpenAPI Specification's definition, the [`consumes`](#operationConsumes) property of an operation). This is the only parameter type that can be used to send files, thus supporting the `file` type. Since form parameters are sent in the payload, they cannot be declared together with a body parameter for the same operation. Form parameters have a different format based on the content-type used (for further details, consult http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4):
   * `application/x-www-form-urlencoded` - Similar to the format of Query parameters but as a payload. For example, `foo=1&bar=swagger` - both `foo` and `bar` are form parameters. This is normally used for simple parameters that are being transferred.
   * `multipart/form-data` - each parameter takes a section in the payload with an internal header. For example, for the header `Content-Disposition: form-data; name="submit-name"` the name of the parameter is `submit-name`. This type of form parameters is more commonly used for file transfers.
 
 * Cookie - Used to pass a specific cookie value to the API.
 
 
-For complex parameter schemas, a serialization strategy is required. For parameter of type `in: body`, the serialization will be handled by the `consumes` attribute.  For all other types, a serialization strategy must be declared.
+For complex parameter schemas, a serialization strategy is required. For all types, a serialization strategy must be declared.
 
 ##### Fixed Fields
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterName"></a>name | `string` | **Required.** The name of the parameter. Parameter names are *case sensitive*. <ul><li>If [`in`](#parameterIn) is `"path"`, the `name` field MUST correspond to the associated path segment from the [path](#pathsPath) field in the [Paths Object](#pathsObject). See [Path Templating](#pathTemplating) for further information.<li>For all other cases, the `name` corresponds to the parameter name used based on the [`in`](#parameterIn) property.</ul>
-<a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path", "formData", "body", or "cookie".
+<a name="parameterIn"></a>in | `string` | **Required.** The ___location of the parameter. Possible values are "query", "header", "path", "formData" or "cookie".
 <a name="parameterDescription"></a>description | `string` | A brief description of the parameter. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="parameterRequired"></a>required | `boolean` | Determines whether this parameter is mandatory. If the parameter is [`in`](#parameterIn) "path", this property is **required** and its value MUST be `true`. Otherwise, the property MAY be included and its default value is `false`. 
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and should be transitioned out of usage.
@@ -628,59 +628,6 @@ Field Pattern | Type | Description
 
 ##### Parameter Object Examples
 
-###### Body Parameters
-
-A body parameter with a referenced schema definition (normally for a model definition):
-```js
-{
-  "name": "user",
-  "in": "body",
-  "description": "user to add to the system",
-  "required": true,
-  "schema": {
-    "$ref": "#/definitions/User"
-  }
-}
-```
-
-```yaml
-name: user
-in: body
-description: user to add to the system
-required: true
-schema:
-  $ref: '#/definitions/User'
-```
-
-A body parameter that is an array of string values:
-```js
-{
-  "name": "user",
-  "in": "body",
-  "description": "user to add to the system",
-  "required": true,
-  "schema": {
-    "type": "array",
-    "items": {
-      "type": "string"
-    }
-  }
-}
-```
-
-```yaml
-name: user
-in: body
-description: user to add to the system
-required: true
-schema:
-  type: array
-  items:
-    type: string
-```
-
-###### Other Parameters
-
 A header parameter with an array of 64 bit integer numbers:
 
 ```js
@@ -786,9 +733,88 @@ schema:
   type: file
 ```
 
+#### <a name="requestBodyObject"></a>Request Body Object
+
+Describes a single request body.
+
+The `Content-Type` of the request body must be specified by the `consumes` attribute, either at the [top-level](#oasConsumes) or [operation level](#operationConsumes).
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
+<a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
+<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by mime type.
+<a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
+
+
+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="parameterExtensions"></a>^x- | Any | Allows extensions to the OpenAPI Schema. The field name MUST begin with `x-`, for example, `x-internal-id`. The value can be `null`, a primitive, an array or an object. See [Vendor Extensions](#vendorExtensions) for further details.
+
+
+##### Request Body Examples
+
+A request body with a referenced model definition.
+```js
+{
+  "description": "user to add to the system",
+  "schema": {
+    "$ref": "#/definitions/User"
+  },
+  "examples": {
+        "application/json": {
+          "$ref": 'http://foo.bar#/examples/address-example.json'
+        'application/xml':
+          $ref: 'http://foo.bar#/examples/address-example.xml'
+        'text/plain':
+          $ref: 'http://foo.bar#/examples/address-example.txt'
+        default:
+          $ref: 'http://foo.bar#/examples/address-example.whatever'
+}
+```
+
+```yaml
+description: user to add to the system
+schema:
+  $ref: '#/definitions/User'
+examples:
+        'application/json':
+          $ref: 'http://foo.bar/examples/user-example.json'
+        'application/xml':
+          $ref: 'http://foo.bar/examples/user-example.xml'
+        'text/plain':
+          $ref: 'http://foo.bar/examples/user-example.txt'
+        default:
+          $ref: 'http://foo.bar/examples/user-example.whatever'
+```
+
+A body parameter that is an array of string values:
+```js
+{
+  "description": "user to add to the system",
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "string"
+    }
+  }
+}
+```
+
+```yaml
+description: user to add to the system
+required: true
+schema:
+  type: array
+  items:
+    type: string
+```
+
 #### <a name="itemsObject"></a>Items Object
 
-A limited subset of JSON-Schema's items object. It is used by parameter definitions that are not located [`in`](#parameterIn) `"body"`.
+A limited subset of JSON-Schema's items object. It is used by parameter definitions.
 
 ##### Fixed Fields
 Field Name | Type | Description
@@ -1060,7 +1086,7 @@ X-Rate-Limit-Reset:
 
 #### <a name="exampleObject"></a>Example Object
 
-Allows sharing examples for operation responses.
+Allows sharing examples for operation requests and responses.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -1069,7 +1095,7 @@ Field Pattern | Type | Description
 
 ##### Example Object Example
 
-Example response for application/json mimetype of a Pet data type:
+Example request or response for application/json mimetype of a Pet data type:
 
 ```js
 {
@@ -1184,10 +1210,8 @@ definitions:
       example:
         $ref: http://foo.bar#/examples/name-example
 
-# in a parameter, note the plural `examples` as the content-type is set by `consumes`:
-  parameters:
-    - name: address
-      in: body
+# in a request body, note the plural `examples` as the content-type is set by `consumes`:
+	requestBody:
       schema:
         $ref: '#/definitions/Address'
       examples:
@@ -1199,6 +1223,10 @@ definitions:
           $ref: 'http://foo.bar#/examples/address-example.txt'
         default:
           $ref: 'http://foo.bar#/examples/address-example.whatever'
+
+# in a parameter
+
+  parameters:
     - name: 'zip'
       in: 'query'
       type: 'string'
