如何调试FastAPI OpenAPI生成错误：添加OAuth2PasswordRequestForm后报KeyError

这个KeyError是FastAPI生成OpenAPI接口文档时，自动为OAuth2PasswordRequestForm生成的动态Pydantic模型没有被正确注册到模型映射表中导致的，常见触发原因有3种：

1. FastAPI与Pydantic版本不兼容：如果使用0.100.0以下版本的FastAPI搭配Pydantic v2，就会出现动态模型注册异常，这是最高发的场景
2. 自定义OpenAPI生成逻辑时过滤了动态模型：如果项目中重写了get_openapi函数，手动修改了model_name_map，可能会把自动生成的Body_开头的动态表单模型排除
3. 路由重复注册：同一个登录接口被多次挂载到路由实例上，导致同一个动态模型被重复生成，出现注册冲突

• 首先核对依赖版本：执行命令pip list | findstr fastapi和pip list | findstr pydantic查看版本：
  • 如果FastAPI版本<0.100.0且Pydantic版本为v2，直接升级FastAPI到最新稳定版即可解决
  • 要是不想升级FastAPI，把Pydantic降级到1.10.x版本也可以
• 检查自定义OpenAPI逻辑：如果项目中存在自定义custom_openapi的代码，确认是否手动过滤了Body_开头的动态模型，把这类模型加入model_name_map即可
• 检查路由注册逻辑：确认登录接口所在的路由文件没有被重复导入、重复挂载到APIRouter或者FastAPI实例上
• 替代方案验证：把OAuth2PasswordRequestForm依赖替换为手动声明的Form参数，验证文档是否能正常加载，示例如下：

from fastapi import Form
from fastapi.security import OAuth2PasswordRequestForm

@router.post("/login/access-token", response_model=schemas.Token)
def login_access_token(
    db: Session = Depends(deps.get_db), 
    username: str = Form(),
    password: str = Form()
) -> Any:
    # 手动组装成OAuth2PasswordRequestForm结构，不影响原有认证逻辑
    form_data = OAuth2PasswordRequestForm(username=username, password=password, scope="")
    # 后续原有逻辑保持不变

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