Swagger中multipart/form-data请求fileDate字段类型匹配失败问题

问题详情 #

我用Swagger定义了一个给项目关联文件的上传接口，PUT请求的Swagger定义如下：

put:
  tags:
    - files
  description: 给项目添加关联文件
  operationId: addFile
  parameters:
    - name: projectId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  requestBody:
    content:
      multipart/form-data:
        schema:
          $ref: "#/components/schemas/AddFileToProjectRequestBody"
    required: true
  responses:
    200:
      description: 操作成功
      content: {}

对应的Schema定义：

AddFileToProjectRequestBody:
    required:
      - file
    type: object
    properties:
      file:
        type: string
        format: binary
        description: 要上传的文件
      fileDate:
        type: integer
        format: int64
        minimum: 0
        description: 文件修改日期（毫秒级Unix时间戳）

仅上传文件时接口正常工作，但添加fileDate参数后会触发如下错误：

"request body has an error: doesn't match the schema: Error at "/fileDate": Field must be set to integer or not be present"

传入的数值无法被识别为整数，我尝试将fileDate改为string类型后可以正常运行，但用字符串存储日期并不符合语义规范。

补充请求示例：

------WebKitFormBoundaryGs2
Content-Disposition: form-data; name="fileDate"

1670485649000
------WebKitFormBoundaryGs2
Content-Disposition: form-data; name="projectFile"; filename="1.txt"
Content-Type: text/plain


------WebKitFormBoundaryGs2--

问题原因 #

multipart/form-data格式的请求中，所有表单字段默认都是以纯文本字符串的形式传输的——哪怕你输入的是数字，HTTP请求里它依然是字符串类型。而你的Swagger Schema把fileDate定义为integer类型，校验器会严格检查字段的原始数据类型，不会自动执行字符串到整数的转换，因此直接触发了类型不匹配的校验错误。

可行解决方案 #

1. Swagger层面配置类型转换：在multipart/form-data的encoding节点中为fileDate指定类型转换规则，告诉校验器将接收到的字符串值转换为整数。示例修改如下：

   requestBody:
     content:
       multipart/form-data:
         schema:
           $ref: "#/components/schemas/AddFileToProjectRequestBody"
         encoding:
           fileDate:
             schema:
               type: integer
               format: int64
   

   不同的Swagger实现（比如SpringDoc、Swagger UI）可能需要配合额外的扩展字段或配置，具体可参考对应工具的文档。

2. 后端手动转换：如果Swagger层面的配置无法生效，可以在后端接口逻辑里，将接收到的fileDate字符串手动转换为int64类型后再处理。这种方式既能保持Swagger Schema的语义正确性，又能兼容multipart请求的传输限制。

3. 临时使用字符串类型（不推荐）：如果上述两种方式都无法实现，可暂时将Schema中的fileDate改为string类型，并在描述中明确说明是毫秒级时间戳字符串，但这种方式会丢失类型校验的严谨性，仅作为应急方案。

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