FastAPI中为响应体添加多个示例以展示在API文档

原代码中通过json_schema_extra配置的examples仅对请求体的Schema生效，要实现响应体的多示例下拉选择，需要在路由中单独配置响应示例。以下是两种可行方案：

方案一：通过路由responses参数定义响应示例 #

直接在路由装饰器中指定状态码对应的响应示例，可为每个示例设置名称、描述和具体内容：

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    value: str

@app.get(
    path="/",
    responses={
        200: {
            "description": "返回的Item对象",
            "content": {
                "application/json": {
                    "examples": {
                        "Normal Example": {
                            "summary": "普通示例",
                            "value": {"value": "A normal example"}
                        },
                        "Converted Data Example": {
                            "summary": "转换后数据示例",
                            "value": {"value": "An example with converted data"}
                        },
                        "Invalid Data Example": {
                            "summary": "无效数据示例（仅展示用）",
                            "value": {"value": "Invalid data ..."}
                        }
                    }
                }
            }
        }
    }
)
def get1() -> Item:
    return Item(value="a")

if __name__ == "__main__":
    uvicorn.run(app)

方案二：使用Annotated结合响应模型配置示例（FastAPI 0.99.0+） #

通过Annotated包裹返回类型，搭配Response的examples参数定义多示例：

import uvicorn
from fastapi import FastAPI, Response
from pydantic import BaseModel
from typing import Annotated

app = FastAPI()

class Item(BaseModel):
    value: str

# 定义响应示例集合
response_examples = {
    "Normal Example": {
        "summary": "普通示例",
        "value": {"value": "A normal example"}
    },
    "Converted Data Example": {
        "summary": "转换后数据示例",
        "value": {"value": "An example with converted data"}
    },
    "Invalid Data Example": {
        "summary": "无效数据示例（仅展示用）",
        "value": {"value": "Invalid data ..."}
    }
}

@app.get(path="/")
def get1() -> Annotated[Item, Response(examples=response_examples)]:
    return Item(value="a")

if __name__ == "__main__":
    uvicorn.run(app)

关键说明 #

• json_schema_extra中的examples仅作用于请求体的Schema定义，不会影响响应体的示例展示。
• 两种方案均可在API文档的响应区域生成下拉选择框，支持切换查看不同示例内容。

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