Multiple and mixed media type guidelines

[pvdbosch]

Elaborate guidelines on media types:

• multiple media types (with different schemas) in OpenAPI request/response: do we support it? See generator problems below.
• list supported media types instead of generic */*
• example with multipart/form-data
  • considerations: better efficiency than inline base64 binary
  • recommend to put all structured data in a JSON (instead of separate parts at root level)
  • specify encoding https://spec.openapis.org/oas/v3.0.3#encoding-object for non-default media type mappings
  • this is probably the most used multipart type. multipart/related can also be used but is less common; it supposed to be a root document which references annexes

Note that different schemas per media type aren't well supported by code generators (openapi generator). It just generates for the first specified media type and doesn't seem to take encoding spec into consideration.

Multiple schemas in input (JAX-RS):

     requestBody:
       required: true
       content:
         application/json:
           schema:
             $ref: "#/components/schemas/Request"
         application/octet-stream:
           schema:
             type: string
             format: binary

[WARNING] Multiple schemas found in the OAS 'content' section, returning only the first one (application/json)
[WARNING] Multiple MediaTypes found, using only the first one

for response:

• https://github.com/OpenAPITools/openapi-generator/issues/6126
• https://github.com/OpenAPITools/openapi-generator/issues/8119

multipart/form-data response in spring generates the POJO with a schema and application/json Content-Type. To workaround:

          <schemaMappings>
                                <schemaMapping>Logo=org.springframework.util.MultiValueMap</schemaMapping>
                            </schemaMappings>