FastAPI因OAuth2PasswordRequestForm问题无法加载SwaggerUI API文档

问题现象 #

FastAPI站点运行正常，但SwaggerUI（/docs）无法加载。移除f: OAuth2PasswordRequestForm = Depends()参数后，API文档可正常访问，但该参数是HTML登录表单获取用户输入必需的。

相关代码 #

后端Python代码 #

# 渲染登录页面
@router.get('/login',response_class=HTMLResponse)
def login(request : Request):
        return templates.TemplateResponse("login.html", {"request": request})

# 验证用户后生成令牌
@router.post('/login', response_class=HTMLResponse)
def login(request : Request, f: OAuth2PasswordRequestForm = Depends()):
        data = generate(f.username,f.password )
        if data:
            access_token = create_token(data={"sub": f.username})
            return templates.TemplateResponse("authenticated.html", {"request": request, "data" : data, "access_token": access_token, "token_type": "bearer"}) 

前端HTML表单代码 #

<form method="POST">
    <h5> 访问站点</h5></br>
    <input class="input-box" type="username" placeholder="输入用户名" name="username" required><br><br>  
    <input class="input-box" type="password" placeholder="输入密码" name="password" required><br><br>  
    <button class="login_button"  type="submit">登录</button><br>   
    <br>
</form>  

报错信息 #

File "/usr/local/lib/python3.9/site-packages/fastapi/openapi/utils.py", line 423, in get_openapi
    definitions = get_model_definitions(
  File "/usr/local/lib/python3.9/site-packages/fastapi/utils.py", line 49, in get_model_definitions
    model_name = model_name_map[model]
KeyError: <class 'pydantic.main.Body_login_login_post'>

解决方法 #

方案一：排除HTML表单接口出现在API文档中 #

给POST类型的/login接口添加include_in_schema=False参数，让FastAPI生成OpenAPI文档时跳过该接口，避免模型解析冲突：

修改后的POST接口代码：

@router.post('/login', response_class=HTMLResponse, include_in_schema=False)
def login(request : Request, f: OAuth2PasswordRequestForm = Depends()):
        data = generate(f.username,f.password )
        if data:
            access_token = create_token(data={"sub": f.username})
            return templates.TemplateResponse("authenticated.html", {"request": request, "data" : data, "access_token": access_token, "token_type": "bearer"}) 

原理说明 #

该报错源于FastAPI在生成OpenAPI schema时，对返回HTMLResponse的POST接口处理OAuth2PasswordRequestForm时，自动创建的Body模型出现命名冲突或无法识别的情况，导致抛出KeyError。通过include_in_schema=False排除该接口后，SwaggerUI不再尝试解析该接口的模型，即可正常加载。

方案二：分离HTML表单接口与API登录接口 #

将HTML表单提交的接口（如/login）和供API调用的登录接口（如/api/login）分开实现，API文档仅处理/api/login接口，避免两种场景的冲突。此方案适合需要同时提供HTML登录和API登录的场景。

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