如何在FastAPI中自定义ReDoc OpenAPI文档的响应消息？

要在ReDoc中显示自定义的响应码和描述，你可以通过FastAPI路由的responses参数逐个配置，或者通过自定义OpenAPI Schema实现全局统一配置，以下是具体实现方案：

一、单个路由配置响应码及描述 #

修改代码，在每个路由装饰器中添加responses参数定义状态码和对应描述，同时补充异常抛出逻辑让接口实际返回对应状态码：

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
import uvicorn

app = FastAPI()

class User(BaseModel):
    username: str

user_list = ["John", "Abrahim", "Kiana"]

# Get方法：获取用户
@app.get('/user/{id}/', responses={
    status.HTTP_200_OK: {"description": "一切正常，请求执行符合预期。"},
    status.HTTP_400_BAD_REQUEST: {"description": "请求不可接受，通常因缺少必填参数。"},
    status.HTTP_401_UNAUTHORIZED: {"description": "未提供有效的API密钥。"},
    status.HTTP_403_FORBIDDEN: {"description": "API密钥无权限执行该请求。"},
    status.HTTP_404_NOT_FOUND: {"description": "请求的资源不存在。"},
    status.HTTP_429_TOO_MANY_REQUESTS: {"description": "请求过于频繁，建议采用指数退避策略。"},
    status.HTTP_500_INTERNAL_SERVER_ERROR: {"description": "服务器端出现错误（此类情况较少见）。"}
})
def users(id: int):
    if id < 0 or id >= len(user_list):
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="请求的资源不存在。")
    return user_list[id]

# Post方法：添加用户
@app.post('/user', responses={
    status.HTTP_200_OK: {"description": "一切正常，请求执行符合预期。"},
    status.HTTP_400_BAD_REQUEST: {"description": "请求不可接受，通常因缺少必填参数。"},
    status.HTTP_401_UNAUTHORIZED: {"description": "未提供有效的API密钥。"},
    status.HTTP_402_PAYMENT_REQUIRED: {"description": "参数合法但请求执行失败。"},
    status.HTTP_403_FORBIDDEN: {"description": "API密钥无权限执行该请求。"},
    status.HTTP_409_CONFLICT: {"description": "请求与其他请求冲突（可能因使用相同幂等键）。"},
    status.HTTP_429_TOO_MANY_REQUESTS: {"description": "请求过于频繁，建议采用指数退避策略。"},
    status.HTTP_500_INTERNAL_SERVER_ERROR: {"description": "服务器端出现错误（此类情况较少见）。"}
})
def add_user(request: User):
    if request.username in user_list:
        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="请求与其他请求冲突（可能因使用相同幂等键）。")
    user_list.append(request.username)
    return request.username

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

二、全局统一配置响应码（复用性更高） #

如果多个路由需要重复使用相同的响应码描述，可以通过自定义OpenAPI Schema全局配置，避免重复代码：

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
import uvicorn
from fastapi.openapi.utils import get_openapi

app = FastAPI()

# 定义全局通用响应码描述
COMMON_RESPONSES = {
    status.HTTP_200_OK: {"description": "一切正常，请求执行符合预期。"},
    status.HTTP_400_BAD_REQUEST: {"description": "请求不可接受，通常因缺少必填参数。"},
    status.HTTP_401_UNAUTHORIZED: {"description": "未提供有效的API密钥。"},
    status.HTTP_402_PAYMENT_REQUIRED: {"description": "参数合法但请求执行失败。"},
    status.HTTP_403_FORBIDDEN: {"description": "API密钥无权限执行该请求。"},
    status.HTTP_404_NOT_FOUND: {"description": "请求的资源不存在。"},
    status.HTTP_409_CONFLICT: {"description": "请求与其他请求冲突（可能因使用相同幂等键）。"},
    status.HTTP_429_TOO_MANY_REQUESTS: {"description": "请求过于频繁，建议采用指数退避策略。"},
    status.HTTP_500_INTERNAL_SERVER_ERROR: {"description": "服务器端出现错误（此类情况较少见）。"},
    status.HTTP_502_BAD_GATEWAY: {"description": "服务器端出现错误（此类情况较少见）。"},
    status.HTTP_503_SERVICE_UNAVAILABLE: {"description": "服务器端出现错误（此类情况较少见）。"},
    status.HTTP_504_GATEWAY_TIMEOUT: {"description": "服务器端出现错误（此类情况较少见）。"}
}

# 自定义OpenAPI Schema
def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    openapi_schema = get_openapi(
        title="用户管理API",
        version="1.0.0",
        description="用于用户增查的API服务",
        routes=app.routes,
    )
    # 为每个路径的每个方法添加全局通用响应
    for path in openapi_schema["paths"].values():
        for method in path.values():
            method["responses"].update(COMMON_RESPONSES)
    app.openapi_schema = openapi_schema
    return app.openapi_schema

app.openapi = custom_openapi

class User(BaseModel):
    username: str

user_list = ["John", "Abrahim", "Kiana"]

@app.get('/user/{id}/')
def users(id: int):
    if id < 0 or id >= len(user_list):
        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="请求的资源不存在。")
    return user_list[id]

@app.post('/user')
def add_user(request: User):
    if request.username in user_list:
        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="请求与其他请求冲突（可能因使用相同幂等键）。")
    user_list.append(request.username)
    return request.username

if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=8000)

效果验证 #

启动服务后，访问http://127.0.0.1:8000/redoc，即可看到每个接口下已配置的所有响应码及对应的自定义描述。

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