FastAPI Swagger文档显示错误响应状态码，如何排查原因？

FastAPI生成OpenAPI文档的底层机制 #

FastAPI的接口文档（包括Swagger）是启动时静态分析代码生成的，核心依据是：

• 路由装饰器的参数（比如status_code、responses）
• 函数的类型提示、Pydantic模型定义
• 抛出的HTTPException类型

它不会解析函数内部的注释文本，也不会识别你手动通过response.status_code设置的状态码——因为这些都是运行时的动态操作，启动时的静态分析无法捕获。

你的代码问题分析 #

1. 422状态码出现的原因：因为你用了Form()获取参数，FastAPI会自动对表单参数做校验，如果请求缺少email/password、或者参数类型不匹配，框架会直接返回422（请求格式错误），这是FastAPI对表单/查询参数校验失败的默认行为，属于正常的自动生成项。

2. 400、409、201未显示的原因：

   • 你在函数内部通过response.status_code设置的201、400、409都是运行时动态修改的，静态分析阶段抓不到这些值
   • 注释里写的响应状态码只是纯文本，FastAPI不会解析注释内容来生成文档

解决办法 #

要让这些状态码出现在Swagger文档里，需要在路由装饰器里显式声明：

方法1：用status_code和responses参数 #

修改路由装饰器，指定成功状态码和所有预期的错误响应：

from fastapi import status

@app.post(
    path='/user/create/',
    status_code=status.HTTP_201_CREATED,  # 显式指定成功状态码
    responses={
        400: {"description": "Bad email id supplied."},
        409: {"description": "User already signed up, hence causing conflict with existing id."}
    }
)
async def create_user(response: Response,
                      email: str = Form(),
                      password: str = Form()) -> None:
    # 原函数逻辑不变

方法2：改用HTTPException抛出错误 #

把手动设置状态码改成抛出HTTPException，FastAPI会自动识别这些异常的状态码并添加到文档：

from fastapi import HTTPException

async def create_user(response: Response,
                      email: str = Form(),
                      password: str = Form()) -> None:
    logging.info(msg=f'New user sign up request from {email}.')
    try:
        user: WebUser = WebUser(email=email, password=password)
        created = await user.create_new()
        if not created:
            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="User already signed up")
    except ValidationError:
        logging.error(msg=f'User creation for {email} failed because of bad request.')
        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Bad email id supplied.")

结论 #

这不是FastAPI的Bug，是因为你没有遵循FastAPI文档生成的规则——必须显式声明状态码，而不是靠运行时动态设置或注释文本。按照上面的方法修改后，Swagger文档就会正确显示你预期的所有状态码。

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