FastAPI/OpenAPI中是否支持定义多个不同的响应模型？

完全可行，基于Pydantic原生能力和配套的OpenAPI生成逻辑，不需要额外魔改就能同时满足两套及以上响应结构的校验、序列化，以及OpenAPI JSON的正确结构展示，具体落地方案分两种场景：

场景1：不同HTTP状态码对应不同响应结构 #

这是最常见的业务分支返回场景，直接在接口声明层绑定不同状态码对应的Pydantic模型即可，以和Pydantic适配最成熟的FastAPI为例：

• 先定义两套独立的Pydantic模型

from pydantic import BaseModel
from fastapi import FastAPI

app = FastAPI()

# 第一套：正常流程响应结构
class SuccessResp(BaseModel):
    code: int
    biz_data: dict
    request_id: str

# 第二套：特殊业务分支响应结构
class SpecialBizResp(BaseModel):
    err_no: int
    err_tip: str
    trace_id: str

• 在接口装饰器的responses参数中绑定不同状态码对应的模型

@app.get(
    "/biz/handle",
    responses={
        200: {"model": SuccessResp, "description": "常规业务成功返回"},
        210: {"model": SpecialBizResp, "description": "特殊业务分支返回"}
    }
)
def handle_biz(trigger_special: bool):
    if not trigger_special:
        # 返回内容自动按SuccessResp做校验、序列化
        return SuccessResp(code=0, biz_data={"res": "done"}, request_id="req_123")
    # 返回内容自动按SpecialBizResp做校验、序列化
    return SpecialBizResp(err_no=10086, err_tip="触发特殊逻辑", trace_id="trace_456")

• 最终生成的OpenAPI JSON中，两个状态码的响应会分别绑定对应模型的完整Schema，不会出现结构混淆。如果不使用FastAPI，直接调用Pydantic自带的model_json_schema()方法就能导出每个模型的Schema结构，手动注册到OpenAPI的components.schemas节点、在对应路径的响应字段中引用即可。

场景2：同一HTTP状态码下返回不同结构 #

如果两套响应走同一个HTTP状态码，只是业务字段完全不同，用Pydantic的判别联合（Discriminated Union）实现即可，OpenAPI会自动生成oneOf结构标识两套模型，校验序列化时也能自动匹配对应规则：

• 给两个模型增加统一的类型鉴别字段，绑定字面量值用于区分结构

from pydantic import BaseModel
from typing import Literal, Union

class VipUserResp(BaseModel):
    resp_type: Literal["vip"]
    user_id: int
    vip_level: int
    expire_timestamp: int

class NormalUserResp(BaseModel):
    resp_type: Literal["normal"]
    user_id: int
    register_timestamp: int
    last_login_timestamp: int

• 定义带鉴别器的联合类型作为接口响应模型

# 声明联合响应类型，指定鉴别字段
UserInfoResp = Union[VipUserResp, NormalUserResp]

@app.get("/user/info", response_model=UserInfoResp)
def get_user_info(user_id: int):
    user = query_user(user_id)
    if user.is_vip:
        return VipUserResp(
            resp_type="vip",
            user_id=user_id,
            vip_level=user.vip_grade,
            expire_timestamp=user.vip_expire
        )
    return NormalUserResp(
        resp_type="normal",
        user_id=user_id,
        register_timestamp=user.register_time,
        last_login_timestamp=user.last_login
    )

避坑提示 #

• 不要返回无类型的裸字典，必须返回对应Pydantic模型实例，避免校验遗漏、序列化字段缺失
• 同状态码下的多结构返回不要用无鉴别器的普通Union类型，否则Pydantic会按模型定义顺序做匹配，容易出现结构匹配错误，OpenAPI中也无法清晰展示两个结构的区分逻辑
• 自定义响应头、Cookie等附加返回内容不会影响模型的Schema生成，正常在responses参数中声明即可

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