Merge pull request #3864 from handrews/request-examples-304

Improve media type serialization examples (3.0.4)

versions/3.0.4.md

@@ -1302,7 +1302,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
 
 ##### Request Body Examples
 
-A request body with a referenced model definition.
+A request body with a referenced schema definition.
 ```json
 {
   "description": "user to add to the system",
@@ -1378,35 +1378,6 @@ content:
         externalValue: http://foo.bar/examples/user-example.whatever
 ```
 
-A body parameter that is an array of string values:
-```json
-{
-  "description": "user to add to the system",
-  "content": {
-    "text/plain": {
-      "schema": {
-        "type": "array",
-        "items": {
-          "type": "string"
-        }
-      }
-    }
-  }
-}
-```
-
-```yaml
-description: user to add to the system
-required: true
-content:
-  text/plain:
-    schema:
-      type: array
-      items:
-        type: string
-```
-
-
 #### <a name="mediaTypeObject"></a>Media Type Object
 Each Media Type Object provides schema and examples for the media type identified by its key.
 
@@ -1566,9 +1537,35 @@ requestBody:
             properties: {}
 ```
 
-In this example, the contents in the `requestBody` MUST be stringified per [RFC1866](https://tools.ietf.org/html/rfc1866) when passed to the server.  In addition, the `address` field complex object will be stringified.
+In this example, the contents in the `requestBody` MUST be encoded per [RFC1866](https://tools.ietf.org/html/rfc1866) when passed to the server.  In addition, the `address` field complex object will be serialized to a string representation prior to encoding.
+
+When passing complex objects in the `application/x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [Encoding Object](#encodingObject)'s [`style`](#encodingStyle) property as `form`.
+
+With this example, given an `id` of `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` and a US-style address (with ZIP+4) as follows:
+
+```json
+{
+  "streetAddress": "123 Example Dr.",
+  "city": "Somewhere",
+  "state": "CA",
+  "zip": "99999+1234"
+}
+```
+
+Assuming the most compact representation of the JSON value (with unnecessary whitespace removed), we would expect to see the following request body, where space characters have been replaced with `+` and `+`, `"`, `{`, and `}` have been percent-encoded to `%2B`, `%22`, `%7B`, and `%7D`, respectively:
 
-When passing complex objects in the `application/x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [`Encoding Object`](#encodingObject)'s [`style`](#encodingStyle) property as `form`.
+```urlencoded
+id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:%2299999%2B1234%22%7D
+```
+
+Note that the `id` keyword is treated as `text/plain` per the [Encoding Object](#encodingObject)'s default behavior, and is serialized as-is.
+If it were treated as `application/json`, then the serialized value would be a JSON string including quotation marks, which would be percent-encoded as `%22`.
+
+Here is the `id` parameter (without `address`) serialized as `application/json` instead of `text/plain`, and then encoded per RFC1866:
+
+```urlencoded
+id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
+```
 
 ##### Special Considerations for `multipart` Content