Support style, explode, allowReserved encoding for multipart/form-data

[mkistler]

This PR extends the style, explode, and allowReserved of the Encoding Object to also apply to request bodies with a content-type of multipart/form-data.

As discussed in the OpenAPI TSC meeting on 11/21/19, multipart/form-data is just a different serialization of url-encoded form and therefore should support the same set of behaviors.

Fixes #2018.

[darrelmiller]

@OAI/tsc Could you please review, comment and approve. This fix simply corrects the fact that we didn't explicitly call out that both url-encoded forms and multipart/form-data can have parameter serialization customized using style, explode and allowReserved. OpenAPI v2 allowed this and we should still support it in V3.

[MikeRalphson]

Apart from the last sentence, this new paragraph seems to be summarising the defined behaviour of the multipart/form-data spec, not defining how the OAS works in conjunction with it. Is it needed?

[darrelmiller]

I agree. I don't think it is needed.

[mkistler]

I am open to modifying or even removing this paragraph, but let me make a few points:

• I mostly borrowed the wording for this paragraph from the OpenAPI 2.0 spec here. So maybe this was also not needed in the 2.0 spec, but I personally found it helpful and thought we should move it forward to 3.0.

• In particular, I think there is value in describing how schema property values map to form data / payload sections. You may consider this "obvious", but I think it is better for a specification to state the obvious than to leave things undefined.

• In multiple conversations I’ve had on this issue, including in the last TSC, I think there has been agreement that the current spec needs to be clarified on how multipart/form-data is handled. This was my attempt to address that.

• By "the multipart/form-data spec", do you mean RFC 7578? If so, then at the very least I would like to replace this with a reference to that RFC (currently not referenced anywhere in the spec).

So should I take a stab at revising this paragraph or are folks still opposed to providing any explanation/clarification on this?

[darrelmiller]

I missed the fact that you were explaining how the Schema property maps to a parameter in multipart/form-data. I think that aspect is worth clarifying. I think it is important to be explicit about the form-data parameter mapping to the corresponding schema property.

[webron]

@darrelmiller and I had a quick discussion about this. Overall, it solves an issue of something that could be defined in 2.0 that we had no intention of removing in 3.0. The only suggested change is to add a comment on style, explode and allowReserved that if any of them is defined, then contentType should be ignored.

This is to avoid any confusion on how to implement both, as they both speak to how the provided content should be serialized. This leads to feature parity with the regular Parameter Object definition, where you can use either content to define a media type or a combination of style, explode, allowReserved to dictate serialization.

I chose to add it to each of the modifiers instead of contentType to hopefully make it clearer.

[mkistler]

I've merged @webron 's suggested changes and replaced the details of multipart/form-data with a reference to RFC 7578. I think this is ready for re-review.