FastAPI中Swagger UI传Authorization Header失败及请求报错排查

核心错误原因 #

1. 请求体格式不兼容

前端通过FormData构造multipart/form-data格式的请求体，但后端接口用Body(...)声明参数，FastAPI默认会将请求体解析为JSON格式，无法识别FormData中的字段，导致无法匹配email和form_info参数，触发422（请求格式错误）。

2. Header参数解析偏差

后端定义的authorization Header参数，虽HTTP头不区分大小写，但未显式指定别名时，可能存在解析偏差；同时请求体格式错误会导致后端参数解析逻辑提前失败，掩盖真实问题（Swagger的报错是单独测试时未携带Authorization头导致的）。

3. 潜在路径不匹配风险

前端请求路径为${process.env.ENDPOINT}/upload_form_data/，后端路径是/api/queue/upload_form_data/，若process.env.ENDPOINT未包含/api/queue前缀，会触发404错误（当前前端报错为422，说明路径大概率匹配，但需确认环境变量配置）。

修复方案 #

方案一：前端改为发送JSON请求体（推荐）

调整前端代码，改用JSON格式发送请求，符合RESTful规范：

export const uploadFormData = async (
    token: string,
    email: string,
    formInfo: Array<Object>,
): Promise<any> => {
    return fetch(
        `${process.env.ENDPOINT}/api/queue/upload_form_data/`, // 确保路径完整匹配
        {
            method: 'POST',
            headers: {
                'Authorization': `Token ${token}`,
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                email,
                form_info: JSON.stringify({ formInfo })
            }),
        },
    ).then((response) => {
        console.log(response.body?.getReader());
        if (response.status === 404) {
            throw Error('Url not found');
        }
        if (response.status === 422) {
            throw Error('Wrong request format');
        }
        if (response.status !== 200) {
            throw Error('Something went wrong with uploading the form data.');
        }
        return response.json().then(data => ({
            success: true, // 修复原代码拼写错误：succes → success
            data,
        }));
    }).catch((error) => Promise.reject(error));
};

方案二：后端适配FormData格式

若需保留前端FormData发送方式，后端改用Form(...)解析请求体，并显式指定Header别名：

from fastapi import FastAPI, Form, Header

@app.post("/api/queue/upload_form_data/")
async def upload_form_data(
    email: str = Form(...),  
    form_info: str = Form(...), 
    authorization: str = Header(..., alias="Authorization"), # 确保匹配前端发送的头
):
    return 'form data processing'

额外注意事项 #

• 确认前端process.env.ENDPOINT配置值，例如设置为http://localhost:8000，确保请求路径完整匹配后端接口。
• Swagger测试时，需在请求头中添加Authorization: Token {你的token值}，否则会触发"field required"错误。

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