Quart-Schema接口Swagger仅显示application/x-www-urlencoded，无法处理multipart请求

问题 #

我正在使用Quart-Schema，并参考官方文档定义了一个用于multipart调用的端点，代码如下：

@dataclass
class File:
    file: Optional[UploadFile] = None
    title: Optional[str] = None
    description: Optional[str] = None
    type: Optional[str] = None


@bp.post('/<int:entity_id>/files')
@validate_request(File, source=DataSource.FORM)
async def post_file(data: File, entity_id):
    """Add file for entity to database"""

关键部分是source=DataSource.FORM，使其接收表单数据而非JSON。接口本身运行正常，但在自动生成的Swagger文档中，请求体类型仅显示为application/x-www-urlencoded（下拉菜单唯一选项）。仅发送普通字段数据时请求可正常工作，但添加文件后请求失败。

我尚未找到将其改为multipart/form-data的方法，虽见过Swagger示例支持该类型，但这些示例未使用Quart-Schema。似乎source=DataSource.FORM决定了请求体类型，而source仅有DataSource.FORM和DataSource.JSON两个选项，因此无法让Swagger显示/发送multipart/form-data。

请问这是Quart-Schema的限制吗？如果是，有没有解决方案？

解决方案 #

这确实是Quart-Schema当前的设计限制——DataSource.FORM默认只会生成application/x-www-urlencoded的Swagger定义，不会自动识别包含文件字段的情况切换到multipart/form-data。不过有两种可行的解决方案：

1. 手动覆盖OpenAPI请求体定义 #

Quart-Schema允许通过openapi_extra参数给端点添加自定义OpenAPI配置，直接指定请求体的content类型为multipart/form-data，并定义对应字段结构：

@bp.post('/<int:entity_id>/files', openapi_extra={
    "requestBody": {
        "content": {
            "multipart/form-data": {
                "schema": {
                    "type": "object",
                    "properties": {
                        "file": {"type": "string", "format": "binary"},
                        "title": {"type": "string"},
                        "description": {"type": "string"},
                        "type": {"type": "string"}
                    },
                    "required": []  # 根据实际业务调整必填字段
                }
            }
        }
    }
})
@validate_request(File, source=DataSource.FORM)
async def post_file(data: File, entity_id):
    """Add file for entity to database"""

这种方式会覆盖自动生成的Swagger请求体定义，让文档显示multipart/form-data选项，同时不影响后端的校验逻辑——DataSource.FORM本身是支持解析multipart/form-data格式的，之前的请求失败只是因为Swagger默认用x-www-urlencoded发送文件导致的。

2. 扩展Quart-Schema的类型处理逻辑 #

如果需要批量处理多个文件上传端点，可以通过继承Quart-Schema的核心类扩展功能：

• 自定义新的数据源枚举（比如DataSource.MULTIPART）
• 重写validate_request装饰器的OpenAPI生成逻辑，当检测到数据类中包含UploadFile类型字段时，自动将请求体类型设置为multipart/form-data

这种方式需要对Quart-Schema的源码逻辑有一定了解，适合有大量同类端点的场景。

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