Updates to parameter and requestBody

[webron]

Summary of changes:

• Renamed commaDelimited to simple, reference the type in the RFC and made not applicable to query. Described behavior for primitive value, added exploded example.
• Set default style based on parameter type.
• Explained allowEmptyValue is inapplicable if example table value is n/a.
• Added example of free-form query parameters, made explicit typed example.
• Added support for style to header and cookie params - only one style allowed for each.
• Fixed anchors in Encoding Object.
• Changed the default style of x-www-form-urlencoded to form, set behavior to be like query parameters.
• Made contentType not required, described default values.

Note that the behavior of headeer and cookie parameters is different than what we discussed.

header

For values [ red, green, blue ]:

/test:
  get:
    parameters:
    - in: header
      name: colors
      required: true
      type: array
      style: simple
      items:
        type: string

will be colors: red,green,blue regardless of whether explode is true/false.
This is different than the discussed result of explode true represented as:
colors: colors=red&colors=green&colors=blue.

cookie

By following style being form, we get the representation of Set-Cookie: colors=red,green,blue by default, so no extra explanation needed (unlike using simple).

---

Open issues:

• What would explode being true for cookie parameter will look like?
• Many users requested that the collectionFormat by default be multi and not csv. This means that we should set explode to true for query parameters by default. It's a cumbersome explanation (if this then that, otherwise something else), but doable. Opinions welcome.

[fehguy]

simple? Seems like that's a bit harder to figure out without cross-referencing...

[webron]

Reusing the name from https://tools.ietf.org/html/rfc6570#section-3.2.2, like the other style names from there.

[fehguy]

OK sure, but it still sucks

[webron]

Alternatives welcome.

[fehguy]

commaSeparated is a good idea... but we can follow the standard

[webron]

We can discuss it tomorrow. I don't think it's a good idea because unlike in 2.0, it cannot be applied to query and formData (or requestBody now).

csv has been effectively replaced by both simple and form, depending on the situation.

[darrelmiller]

Were there still open issues here? I thought we resolved everything.

[webron]

Per our discussion, changed the default value of explode to true when the style is form and the rest has a default value of false. This makes the default from 2.0 be multi instead of csv.