如何在FastAPI中为UploadFile参数指定默认文件并在Swagger文档展示？

受浏览器安全策略限制，Swagger UI的文件上传控件无法自动填充本地文件路径，以下两种方案可以实现无需每次手动选文件、快速调试接口的需求：

方案1：参数设为可选，后台内置测试默认文件（最实用） #

调试时不手动选择文件的话，接口自动使用你预设的测试文件，无需额外配置Swagger：

import uvicorn
from fastapi import FastAPI
from fastapi.datastructures import UploadFile
from fastapi.params import File
from typing import Optional
import io

app = FastAPI()

# 预设的默认测试文件内容，也可以从本地静态测试文件读取
DEFAULT_TEST_FILE_CONTENT = b"这是默认测试文件的内容\n测试行1\n测试行2"
DEFAULT_TEST_FILENAME = "test_default.txt"

@app.post("/default_file_upload")
def default_file_upload_example(file: Optional[UploadFile] = File(None, description="不选文件则默认使用内置测试文件")):
    # 未传文件时自动初始化默认测试文件
    if not file:
        file = UploadFile(
            file=io.BytesIO(DEFAULT_TEST_FILE_CONTENT),
            filename=DEFAULT_TEST_FILENAME
        )
    # 后续业务逻辑直接处理file对象即可
    return {
        "filename": file.filename,
        "content": file.file.read().decode("utf-8")
    }


if __name__ == "__main__":
    uvicorn.run("test:app", debug=True, port=8000)

使用时直接在Swagger调试界面点「Try it out」，不用选文件直接点「Execute」即可触发默认文件上传逻辑。

方案2：在文档中标注示例文件说明 #

如果需要提示测试人员使用指定的本地测试文件，可以直接给File参数加描述和示例标注，会自动显示在Swagger参数说明区域：

@app.post("/default_file_upload")
def default_file_upload_example(
    file: UploadFile = File(
        ...,
        description="调试建议使用预设测试文件test_demo.csv，内容示例：id,name\n1,张三\n2,李四",
        example="test_demo.csv"
    )
):
    return {}

注意：浏览器出于安全限制禁止JS脚本主动设置文件上传控件的本地路径，因此无法实现打开Swagger调试页面就自动选中本地文件的效果，上述方案已经是可实现的最优解。

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