OpenApi ContentMedia Array and Properties

[mdaneri]

Describe the Feature

Today, Pode allows us to define ContentMedia as a Hashtable. This is enough to represent a simple ContentMedia but not one with arrays or special properties.
Another feature is hiding the complexity of the upload definition and the differences between OpenAPI 3.0.x and 3.1.x

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

Examples

New-PodeOAContentMediaType -MediaType 'image/jpeg','image/png' -Content (
New-PodeOAStringProperty -Format binary)

# multiple, specific media types may be specified:
requestBody:
  content:
      # a binary file of type png or jpeg
    'image/jpeg':
      schema:
        type: string
        format: binary
    'image/png':
      schema:
        type: string
        format: binary

 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'