FastAPI自学教程（53） - OpenAPI额外响应配置

1.基础用法

from fastapi import FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel

class Item(BaseModel):
    id: str
    value: str

class Message(BaseModel):
    message: str

app = FastAPI()

@app.get("/items/{item_id}",
         response_model=Item,
         responses={404: {"model": Message, "description": "未找到项目"}})
async def read_item(item_id: str):
    if item_id != "foo":
        return JSONResponse(status_code=404, content={"message": "Item not found"})
    return {"id": "foo", "value": "there goes my hero"}

• 使用responses参数声明OpenAPI额外响应配置，支持多状态码定义
• 每个响应需要直接返回Response子类实例（如JSONResponse）
• OpenAPI文档自动集成响应模型描述，支持嵌套JSON Schema引用

流程图：

graph TD
    A[客户端请求] --> B{是否匹配主响应?}
    B -->|是| C[返回主响应模型]
    B -->|否| D[查找额外响应配置]
    D --> E{找到匹配状态码?}
    E -->|是| F[返回对应模型]
    E -->|否| G[返回默认错误]

2.模型关联机制

responses={
    400: {
        "model": Message,
        "content": {"application/xml": {"schema": {"$ref": "#/components/schemas/Message"}}}
    }
}

• 通过model参数关联Pydantic模型，自动生成JSON Schema
• 支持多媒体类型声明（如同时支持JSON/XML格式响应）
• 模型验证仅在主响应response_model生效，额外响应需手动验证

3.响应描述增强

responses={
    200: {
        "description": "成功获取项目",
        "content": {"application/json": {"example": {"id": "foo", "value": "bar"}}}
    }
}

• description字段增强文档可读性，支持多语言描述
• content字段支持示例数据展示，提升文档实用性
• 通过example参数提供标准响应样例

4.错误处理集成

@app.get("/items/",
         responses={
             500: {"description": "服务器内部错误"},
             503: {"description": "服务不可用"}
         })
async def read_items():
    # 业务逻辑

• 支持预定义非常规状态码（如503服务不可用）
• 可与HTTPException结合实现统一错误处理
• 生产环境建议将4xx/5xx错误分类声明

5.生产环境建议

1. 文档管理：
   • 使用include_in_schema=False隐藏内部接口
   • 通过deprecated=True标记废弃接口
2. 性能优化：
   • 采用ORJSONResponse提升JSON序列化性能
   • 大文件响应使用StreamingResponse避免内存溢出
3. 安全规范：
   • 错误响应不暴露敏感信息，统一返回简化消息
   • 为认证失败响应添加WWW-Authenticate头部

测试命令查看文档效果：

curl -i http://localhost:8000/items/foo