Add support to OpenAPI 3.1 to use non-string params in multipart/form-data operations

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

• Close this issue

Problem

OpenAPI 3.1 extends the support to customize request generation for non-string params in multipart/form-data requests by using JsonSchema data and supporting more properties from Encoding object. Almost none of these properties are being used by current the OpenAPI 3.1 reader. The OpenAPI 3.1 reader should take advantage of the specific serialization information during request generation.

This issue follows up on the work to add/extend the support to non-string parameters in multipart/form-data requests for OpenAPI 3.1 documents. There was a bug, which was resolved for OpenAPI spec 2.0 and also for OpenAPI 3.0. At this time, only the basic support is shared between OpenAPI 3.0 and OpenAPI 3.1 readers.

Related issues

• #381807 (closed)

Links

• OpenAPI 3.1: Special Considerations for multipart Content
• JsonSchema: Media: string-encoding non-JSON data
• RFC7578: Returning Values from Forms: multipart/form-data

Proposal

For OpenAPI 3.1.x

1. Basic rules to convert Json Schema to multipart/form-data
   1. Add unit test(s) to check default mapping
      1. Using primitives values
      2. Using complex values
      3. Parameter using type: string and contentEncoding
   2. Allow OpenAPI 3.1 reader to map each property to a content part using the following defaults:
      1. If the property is a type: string with a contentEncoding, the default Content-Type is application/octet-stream
      2. If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain
      3. If the property is complex, or an array of complex values, the default Content-Type is application/json
2. Use JSON Schema specification properties contentMediaType, and contentEncoding to provide more serialization details
   1. Add unit test(s)
      1. Supported contentMediaType
      2. Unsupported contentMediaType
      3. Supported contentEncoding
      4. Unsupported contentEncoding
   2. Allow OpenAPI 3.1 reader to check contentMediaType, and contentEncoding to produce request content. ^{NOTE 2}
3. Use Encoding property to provide more details about Content Part serialization
   1. Add unit test(t) checking the use of each Encoding Property used by multipart/form-data.
   2. Modify OpenAPI reader to take into account properties from Encoding Object:
      1. contentType NSwag do not expose contentType (maybe a bug in NSwag)
      2. headers ^{NOTE 1}
      3. style ^{NOTE 1}
      4. explode ^{NOTE 1}
      5. allowReserved ^{NOTE 1}

NOTES:

1. See description in OpenAPI 3.1: Encoding Object
2. As per OpenAPI 3.1 documentation:

   Per the JSON Schema specification, contentMediaType without contentEncoding present is treated as if contentEncoding: identity were present. While useful for embedding text documents such as text/html into JSON strings, it is not useful for a multipart/form-data part, as it just causes the document to be treated as text/plain instead of its actual media type. Use the Encoding Object without contentMediaType if no contentEncoding is required