使用FastAPI接收多文件列表时无文件上传选项问题求助

问题描述 #

我尝试用FastAPI实现多文件接收功能，用了官方示例的代码：

from fastapi import FastAPI, File, UploadFile, HTTPException
from pathlib import Path
from typing import List

@app.post("/uploadfile/")
def create_upload_file(file: List[UploadFile] = File(...)):
    # 后续逻辑

但不管怎么操作，Swagger UI里都看不到文件浏览上传的选项，只能输入随机字符串。可如果把代码改成接收单个UploadFile对象（比如def create_upload_file(file: UploadFile)），功能就完全正常。请问我哪里操作出错了？

问题原因与解决方案 #

我帮你分析下常见的几个问题点和对应的解决方法：

• 参数命名导致Swagger识别异常
  你当前的参数名是单数的file，但类型却是List[UploadFile]，这种单数命名和列表类型的搭配，会让Swagger UI的自动文档生成逻辑混淆，误以为这是单个文本参数而非多文件上传字段。
  解决方法很简单：把参数名改成复数形式，比如files，代码调整后如下：

  @app.post("/uploadfile/")
  def create_upload_file(files: List[UploadFile] = File(...)):
      # 后续逻辑
  

  改完之后刷新Swagger页面，你就能看到可以添加多个文件选择框的上传控件了。

• FastAPI版本兼容性问题
  如果你使用的是较旧版本的FastAPI，可能存在多文件上传控件在Swagger UI中显示异常的bug。建议你升级到最新稳定版，执行命令：

  pip install --upgrade fastapi uvicorn
  

• 类型导入或参数定义不规范
  确认你已经正确导入了from typing import List（你代码里已经做了这步，这点没问题），同时确保File和UploadFile都是从fastapi包中导入的，没有和其他库的同名对象混淆。

调整完之后，再去Swagger UI（默认是http://localhost:8000/docs）测试，应该就能正常看到多文件上传的选项了。

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