如何为FastAPI接口配置额外的可能错误HTTP状态码？

方法一：在路由装饰器中显式声明响应状态码 #

FastAPI支持在路由装饰器（如@app.get）里通过responses参数，直接指定所有可能出现的响应状态码及对应描述，不管异常定义在外部包还是本地代码。

以你的示例代码为例，修改后如下：

from fastapi import FastAPI, HTTPException

app = FastAPI()

# 假设外部包返回的错误码对应401、403、404等状态码
@app.get(
    "/items/{item_id}",
    responses={
        200: {"description": "请求成功，返回资源数据"},
        401: {"description": "未授权，需要验证身份"},
        403: {"description": "权限不足，无法访问该资源"},
        404: {"description": "请求的资源不存在"}
    }
)
async def read_item(item_id: str):
    data, error, message = do_something()
    if error != 0:
        raise HTTPException(status_code=error, detail=message)
    return data

这样Swagger文档（访问/docs）里就会列出这些状态码。如果需要定义每个状态码对应的响应结构，还可以给每个状态码配置model字段，关联对应的Pydantic模型。

方法二：封装外部错误码为自定义异常类 #

如果外部包的错误码可以映射到固定的HTTP状态码，可以把这些错误封装成HTTPException的子类，FastAPI会自动识别这些异常对应的状态码并加入接口文档。

示例代码：

from fastapi import HTTPException
# 假设从外部包导入错误码常量
from external_package import ERROR_UNAUTHORIZED, ERROR_FORBIDDEN, ERROR_NOT_FOUND

class UnauthorizedException(HTTPException):
    def __init__(self, detail: str = "未授权访问"):
        super().__init__(status_code=ERROR_UNAUTHORIZED, detail=detail)

class ForbiddenException(HTTPException):
    def __init__(self, detail: str = "权限不足"):
        super().__init__(status_code=ERROR_FORBIDDEN, detail=detail)

class NotFoundException(HTTPException):
    def __init__(self, detail: str = "资源不存在"):
        super().__init__(status_code=ERROR_NOT_FOUND, detail=detail)

之后在路由逻辑里抛出这些自定义异常即可，无需额外配置，文档会自动同步状态码信息。如果外部错误码较多，也可以写一个工具函数，根据错误码动态生成对应的HTTPException实例。

方法三：批量修改OpenAPI文档（全局生效） #

如果需要给所有接口统一添加相同的错误状态码，可以利用FastAPI的启动钩子，在服务启动后动态修改OpenAPI文档结构：

from fastapi import FastAPI, HTTPException

app = FastAPI()

# 定义全局通用的错误状态码及描述
COMMON_ERROR_RESPONSES = {
    401: {"description": "未授权"},
    403: {"description": "权限不足"},
    404: {"description": "资源不存在"}
}

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    data, error, message = do_something()
    if error != 0:
        raise HTTPException(status_code=error, detail=message)
    return data

# 启动时更新所有接口的响应定义
@app.on_event("startup")
async def update_openapi_docs():
    openapi_schema = app.openapi()
    for path_data in openapi_schema["paths"].values():
        for method_data in path_data.values():
            # 合并原有响应配置和通用错误响应
            method_data["responses"].update(COMMON_ERROR_RESPONSES)
    app.openapi_schema = openapi_schema

这种方式适合需要统一管理所有接口错误状态码的场景，不用逐个路由修改装饰器。

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