如何为multipart/form-data的props部分标记JSON类型并指定Schema？

我有一个API端点，接受包含两部分的multipart/form-data请求体：

• 名为file的非结构化文件
• 名为props的结构化JSON文档

我拥有props的Schema并希望对其进行描述，但用常规方式将Schema嵌入multipart请求体后，生成的OpenAPI文档没有说明props应为序列化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"
            ]
          },
          ...
        }
      },

这种文档会导致Scalar OpenAPI浏览器生成错误的示例：

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

正确的示例应该是：

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

请问是否可以将multipart/form-data的某个部分标记为JSON，并为该JSON指定Schema？

可以实现，需要在OpenAPI规范中为multipart/form-data的props字段指定媒体类型，同时关联对应的Schema，具体步骤如下：

1. 修改请求体的Content描述 #

不再直接引用整个Helper Schema，而是在multipart/form-data的schema下定义每个部分，并为props添加contentMediaType属性：

"requestBody": {
  "content": {
    "multipart/form-data": {
      "schema": {
        "type": "object",
        "required": ["file", "props"],
        "properties": {
          "file": {
            "type": "string",
            "format": "binary"
          },
          "props": {
            "contentMediaType": "application/json",
            "schema": {
              "$ref": "#/components/schemas/UpdateProps"
            }
          }
        }
      }
    }
  },
  "required": true
}

2. 关键说明 #

• contentMediaType: "application/json"：明确标记props部分的内容类型为JSON，告诉OpenAPI工具（如Scalar）该字段需要传入序列化后的JSON字符串，而非表单嵌套字段。
• 保留UpdateProps Schema：既可以复用已有的结构定义，又能让文档清晰展示props的JSON结构细节。

3. 代码层面调整（以Rust aide-axum场景为例） #

如果使用相关辅助库，需要手动扩展Schema生成逻辑：

• 自定义Multipart类型的Schema生成器，为props字段添加contentMediaType属性。
• 或者直接使用aide底层API，手动构建请求体的Schema描述，替代自动生成的Helper类型。

修改后，Scalar等工具就能生成正确的curl示例，OpenAPI文档也能准确反映props字段的JSON要求。

内容的提问来源于stack exchange，提问作者user4815162342