I have an API endpoint that accepts a multipart/form-data body that contains two parts:

• an unstructured file, named file
• a structured JSON document with some properties, named props

I have a schema for props and would like to describe it. When I embed the schema into the multipart request body in the "obvious" way (e.g. using this helper library), the generated OpenAPI document neglects to document that props is supposed to be serialized JSON:

        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Helper_for_UpdateProps"
              }
            }
          },
          "required": true
        },
...
      "Helper_for_UpdateProps": {
        "type": "object",
        "required": [
          "file",
          "props"
        ],
        "properties": {
          "file": ...,
          "props": {
            "$ref": "#/components/schemas/UpdateProps"
          }
        }
      },
...
      "UpdateProps": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          ...
        }
      },

Such a document results in incorrect generated examples in the scalar OpenAPI browser:

$ curl http://localhost:50000 \ 
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=unstructured...' \
  --form 'props[name]=foo' \            
  --form 'props[description]=bar' \
  ...

Instead, the example should look like this:

$ curl http://localhost:50000 \ 
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=unstructured...' \
  --form 'props={"name": "foo", "description": "bar", ...}'

Is it possible to mark a multpart/form-data part as JSON, and to specify schema for that JSON?

I have an API endpoint that accepts a multipart/form-data body that contains two parts:

• an unstructured file, named file
• a structured JSON document with some properties, named props

I have a schema for props and would like to describe it. When I embed the schema into the multipart request body in the "obvious" way (e.g. using this helper library), the generated OpenAPI document neglects to document that props is supposed to be serialized JSON:

        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/Helper_for_UpdateProps"
              }
            }
          },
          "required": true
        },
...
      "Helper_for_UpdateProps": {
        "type": "object",
        "required": [
          "file",
          "props"
        ],
        "properties": {
          "file": ...,
          "props": {
            "$ref": "#/components/schemas/UpdateProps"
          }
        }
      },
...
      "UpdateProps": {
        "type": "object",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ]
          },
          ...
        }
      },

Such a document results in incorrect generated examples in the scalar OpenAPI browser:

$ curl http://localhost:50000 \ 
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=unstructured...' \
  --form 'props[name]=foo' \            
  --form 'props[description]=bar' \
  ...

Instead, the example should look like this:

$ curl http://localhost:50000 \ 
  --request PUT \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=unstructured...' \
  --form 'props={"name": "foo", "description": "bar", ...}'

Is it possible to mark a multpart/form-data part as JSON, and to specify schema for that JSON?

• openapi

• Your OpenAPI schema is actually correct. The issue is with Scalar, send a bug report to them. – Helen Commented 17 hours ago
• @Helen Thanks! I've now tried it on a different editor, and it indeed gets interpreted correctly. Feel free to write that as an answer, I'll accept it. – user4815162342 Commented 14 hours ago

1 Answer 1

Here's an alternative answer using the Encoding Object

openapi: 3.0.4
info:
  title: test
  version: 1.0.0
paths:
  '/thing':
    put:
      summary: a multipart form with serialized json using encoding object
      requestBody:
        description: a description
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                props:
                  $ref: "<reference>"
            encoding:
              file:
                headers:
                  content-disposition:
                    description: mandatory for form-data per RFC7578
                    schema:
                      type: string
                    examples:
                      disposition_header:
                        value: 'content-disposition: form-data; name="file"'
                contentType: application/json
              props:
                headers:
                  content-disposition:
                    description: mandatory for form-data per RFC7578
                    schema:
                      type: string
                    examples:
                      disposition_header:
                        value: 'content-disposition: form-data; name="props"'
                contentType: application/json
      responses:
        '202':
          description: Accepted