New Function to manage OpenAPI 3.x `multipart/form-data` as a `Content-Type` for Multipart upload

[mdaneri]

Describe the Feature

Support for Multipart Upload

New Functions

New-PodeOAContentMediaType

Parameters

• -MediaType An array of strings specifying the media types to be defined. Media types should conform to standard MIME types (e.g., 'application/json', 'image/png'). The function validates these media types against a regular expression to ensure they are properly formatted.

• -Content The content definition for the media type. This could be an object representing the structure of the content expected for the specified media types.

• -Array A switch parameter, used in the 'Array' parameter set, to indicate that the content should be treated as an array.

• -UniqueItems A switch parameter, used in the 'Array' parameter set, to specify that items in the array should be unique.

• -MinItems Used in the 'Array' parameter set to specify the minimum number of items that should be present in the array.

• -MaxItems Used in the 'Array' parameter set to specify the maximum number of items that should be present in the array.

• -Title Used in the 'Array' parameter set to provide a title for the array content.

• -Upload If provided configure the media for an upload changing the result based on the OpenApi version

• -ContentEncoding Define the content encoding for upload (Default Binary)

• -PartContentMediaType Define the content encoding for multipart upload

Why support for multipart Content

It is common to use multipart/form-data as a Content-Type when transferring request bodies to operations. In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content. This supports complex structures as well as supporting mechanisms for multiple file uploads.

When passing in multipart types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default Content-Types are defined for multipart:

• If the property is a primitive, or an array of primitive values, the default Content-Type is text/plain
• If the property is complex, or an array of complex values, the default Content-Type is application/json
• If the property is a type: string with format: binary or format: base64 (aka a file object), the default Content-Type is application/octet-stream

Examples:

 Set-PodeOARequest -RequestBody  (
  New-PodeOARequestBody -Content (
    New-PodeOAContentMediaType -MediaType 'multipart/form-data' -Content (
      New-PodeOAStringProperty -name 'id' -format 'uuid' |
          New-PodeOAObjectProperty -name 'address' -NoProperties |
          New-PodeOAStringProperty -name 'children' -array |
          New-PodeOASchemaProperty -Name 'addresses' -ComponentSchema 'Address' -Array |
          New-PodeOAObjectProperty
      )
    )
 )

requestBody:
  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            type: string
            format: uuid
          address:
            # default Content-Type for objects is `application/json`
            type: object
            properties: {}
          profileImage:
            # default Content-Type for string/binary is `application/octet-stream`
            type: string
            format: binary
          children:
            # default Content-Type for arrays is based on the `inner` type (text/plain here)
            type: array
            items:
              type: string
          addresses:
            # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example)
            type: array
            items:
              type: '#/components/schemas/Address'