如何在FastAPI中生成含错误响应的完整接口响应描述

FastAPI本身就遵循OpenAPI规范，你可以通过几个简单的方式把错误响应的细节（包括状态码、描述和示例）添加到自动生成的API文档里，让前端开发者一目了然。

方法1：直接在路径操作装饰器中定义responses参数 #

这是最直接的方式，你可以在@router.get（或其他请求方法装饰器）里通过responses参数显式声明所有可能的响应，包括错误状态码。结合你的示例代码，修改后如下：

from typing import Any
import uvicorn
from fastapi import FastAPI, HTTPException
router = FastAPI()
from pydantic import BaseModel

class FileItemBase(BaseModel):
    current_project: str = "Test project"

class FileItemInDBBase(FileItemBase):
    id: int
    folder_path: str
    class Config:
        orm_mode = True

class FileResponse(FileItemInDBBase):
    pass

@router.get(
    "/", 
    response_model=FileResponse,
    responses={
        200: {"description": "成功返回文件信息"},
        418: {
            "description": "服务器是茶壶，无法处理该请求（符合HTTP 418玩笑规范）",
            "content": {
                "application/json": {
                    "example": {"detail": "That is a teapot."}
                }
            }
        }
    }
)
def example_code() -> Any:
    """
    # 示例接口：演示错误响应文档生成
    """
    demo=True
    if demo:
        raise HTTPException(418, "That is a teapot.")

if __name__ =="__main__":
    uvicorn.run(router)

这里的关键点： #

• responses是一个字典，键是HTTP状态码，值是该状态码的响应配置
• 对于错误状态码（比如418），你可以指定description说明错误原因，还能通过content添加实际的响应示例，前端开发者直接就能看到错误返回的JSON格式
• 200状态码的描述也可以补充得更清晰，配合response_model的结构，文档会自动关联模型字段

方法2：自定义异常类+全局异常处理器（适合复用的错误类型） #

如果你的项目里有很多地方会抛出相同类型的错误，你可以定义自定义异常类，然后通过全局异常处理器统一处理，同时把这些错误的描述添加到OpenAPI文档中：

from fastapi import Request
from fastapi.responses import JSONResponse

# 自定义异常类
class TeapotException(HTTPException):
    def __init__(self):
        super().__init__(status_code=418, detail="That is a teapot.")

# 全局异常处理器
@router.exception_handler(TeapotException)
async def teapot_exception_handler(request: Request, exc: TeapotException):
    return JSONResponse(
        status_code=exc.status_code,
        content={"detail": exc.detail},
    )

# 然后在路径操作里抛出自定义异常，同时在responses里声明
@router.get(
    "/", 
    response_model=FileResponse,
    responses={418: {"description": "服务器是茶壶，无法处理请求", "content": {"application/json": {"example": {"detail": "That is a teapot."}}}}}
)
def example_code() -> Any:
    demo=True
    if demo:
        raise TeapotException()

这样做的好处是错误逻辑可以复用，同时文档里依然能清晰展示错误响应的细节。

验证效果 #

启动你的FastAPI应用后，访问/docs（Swagger UI）或者/redoc（ReDoc），你就能看到接口的文档里不仅有200的成功响应，还会显示418的错误响应描述和示例，前端开发者不需要测试就能知道如何处理这类场景。

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