documented requestBody

Author: fehguy

versions/3.0.md

@@ -580,7 +580,7 @@ Field Name | Type | Description
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <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="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="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation.  The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <a name="operationCallbacks"></a>callback responses | [Callback Responses Object](#callbackObject) | The list of possible callback responses as they are returned from executing this operation.
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Usage of the declared operation should be refrained. Default value is `false`.
@@ -1124,6 +1124,185 @@ application/json:
 
 ```
 
+##### Considerations for file uploads
+
+In contrast with the 2.0 specification, describing `file` input/output content in OpenAPI is 
+described with the same semantics as any other schema type. Specifically:
+
+```yaml
+# content transferred with base64 encoding
+schema:
+  type: string
+  format: base64
+
+# content transfered in binary (octet-stream):
+schema:
+  type: string
+  format: binary
+
+# mutliple files:
+schema:
+  type: array
+  items:
+    type: string
+    format: binary
+```
+
+Note that the above examples apply to either input payloads (i.e. file uploads) or response payloads.
+
+
+A `requestBody` example for submitting a file in a `POST` operation therefore may look like the following:
+
+```yaml
+requestBody:
+  # any media type is accepted, functionally equivalent to `*/*`
+  application/octet-stream:
+    content:
+      schema:
+        # a binary file of any type
+        type: string
+        format: binary
+```
+
+In addition, specific media types may be specified:
+
+```yaml
+# multiple, specific media types may be specified:
+requestBody:
+  # a binary file of type png or jpeg
+  content:
+    'image/png, image/jpeg':
+      schema:
+        type: string
+        format: binary
+```
+
+##### Support for x-www-form-urlencoded request bodies
+
+To submit content using form url encoding via RFC 1866, the following
+definition may be used:
+
+```yaml
+requestBody:
+  content:
+    x-www-form-urlencoded:
+      schema:
+        type: object
+        properties:
+          id:
+            type: string
+            format: uuid
+          address:
+            # complex types are stringified to support rfc1866
+            type: object
+            properties: {}
+```
+
+Note that in the above example, the contents in the `requestBody` must be stringified per RFC1866 when being passed to the server.  In addition, the `address` field complex object will be strigified as well.
+
+When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `deepObject`.
+
+##### Special Considerations for `mutlipart` content
+
+It is common to use `multipart/form-data` as a `Content-Type` when transferring request bodies to operations.  In contrast to 2.0, a `schema` is required to define the input parameters to the operation when using `multipart` content.  This allows complex structures as well as supports mechanisms for multiple file uploads.
+
+When passing in `multipart` types, boundaries may be used to separate sections of the content being transferred--thus, the following default `Content-Type`s are defined for `multipart/*`:
+
+* If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
+* If the property is complex, or an array of complex values, the default Content-Type is `application/json`
+* If the property is a `type: string` with `format: binary` or `format: base64` (aka a file object), the default Content-Type is `application/octet-stream`
+
+
+Examples:
+
+```yaml
+requestBody:
+  content:
+    multipart/form-data:
+      schema:
+        type: object
+        properties:
+          id:
+            type: string
+            format: uuid
+          address:
+            # default Content-Type for objects is `application/json`
+            type: object
+            properties: {}
+          profileImage:
+            # default Content-Type for string/binary is `application/octet-stream`
+            type: string
+            format: binary
+          children:
+            # default Content-Type for arrays is based on the `inner` type (text/plain here)
+            type: array
+            items:
+              type: string
+          addresses:
+            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
+            type: array
+            items:
+              type: '#/definitions/Address'
+```
+
+In scenarios where more control is needed over the Content-Type for `multipart` request bodies, an `encoding` attribute is introduced.  This attribute is _only_ applicable to `mulitpart/*` request bodies.
+
+#### <a name="encodingObject"></a>Encoding Object
+
+An object representing multipart region encoding for `requestBody` objects
+
+##### Patterned Fields
+Field Pattern | Type | Description
+---|:---:|---
+<a name="encodingObjectProperty"></a>The property to apply encoding to | [Encoding Property](#encodingProperty) <span>&#124;</span> [Encoding](#encoding) | The field name to apply special encoding attributes to.  This field must exist in the schema as a property.  To avoid collisions with specification extensions, properties may not begin with `x-`.
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+#### <a name="encoding"></a>Encoding
+
+A single encoding definition applied to a single schema property
+
+##### Fixed Fields
+Field Name | Type | Description
+---|:---:|---
+<a name="contentType"></a>Content-Type | `string` | **Required.** The content-type to use for encoding a specific property.
+
+This object can be extended with [Specification Extensions](#specificationExtensions). 
+
+##### Encoding Object Examples
+
+```yaml
+requestBody:
+  content:
+    multipart/mixed:
+      schema:
+        type: object
+        properties:
+          id:
+            # default is text/plain
+            type: string
+            format: uuid
+          address:
+            # default is application/json
+            type: object
+            properties: {}
+          historyMetadata:
+            # need to declare XML format!
+            description: metadata in XML format
+            type: object
+            properties: {}
+          profileImage:
+            # default is application/octet-stream, need to declare an image type only!
+            type: string
+            format: binary
+encoding:
+  historyMetadata:
+    # require XML content-type in utf-8 encoding
+    contentType: application/xml; charset=utf-8
+  profileImage:
+    # only accept png/jpeg
+    contentType: image/png, image/jpeg
+```
 
 #### <a name="itemsObject"></a>Items Object