如何在FastAPI文档的响应模型中设置‘黑框’？

这个深色标注框是FastAPI自动生成的OpenAPI文档（即默认的/docs页面）里的响应说明模块，核心是通过指定接口的响应模型与HTTP状态码触发生成，具体实现步骤如下：

• 导入FastAPI和用于定义响应结构的pydantic.BaseModel
• 创建继承自BaseModel的响应模型类，明确接口返回数据的字段与类型
• 在路由装饰器中，通过response_model参数绑定该响应模型，同时可通过status_code指定成功响应的状态码（默认值为200）

基础示例代码 #

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定义响应数据结构模型
class ItemResponse(BaseModel):
    id: int
    name: str
    description: str | None = None

# 绑定响应模型与状态码
@app.get("/items/{item_id}", response_model=ItemResponse, status_code=200)
async def read_item(item_id: int):
    return {"id": item_id, "name": "测试物品", "description": "这是一个示例响应"}

启动服务后访问/docs页面，对应接口的响应区域就会出现标注“Successful Response”的深色框，框内会展示你定义的响应模型结构。

扩展：多状态码响应配置 #

如果需要为不同状态码的响应添加自定义说明，可通过responses参数配置更详细的响应信息，示例如下：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ItemResponse(BaseModel):
    id: int
    name: str

@app.get(
    "/items/{item_id}",
    response_model=ItemResponse,
    responses={
        200: {"description": "成功获取物品详情", "model": ItemResponse},
        404: {"description": "未找到指定物品"}
    }
)
async def read_item(item_id: int):
    if item_id > 10:
        return {"id": item_id, "name": "测试物品"}
    raise HTTPException(status_code=404, detail="物品不存在")

配置后，/docs页面会展示各状态码对应的响应说明框，其中200状态码的框依然会保留“Successful Response”的标注，同时附带你自定义的描述文本。

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