FastAPI如何为内置类型参数声明示例数据并在文档中显示？

针对FastAPI v0.82.0中内置类型Body参数无法通过直接设置Body(example=...)生效的问题，有两种可靠的解决方式：

方式一：使用Pydantic Field定义示例 #

通过pydantic.Field为每个Body参数单独设置示例，FastAPI会自动将这些示例合并到请求体的文档展示中：

1. 先导入Field：

from pydantic import Field

2. 修改接口参数定义：

@app.post('/my_func1/add')  # 注意路径开头需添加/
def func_add(
    id: str = Body(Field(description='this is an id', example='ex_id_123')), 
    content: str = Body(Field(description='this is a content', example='这是一段测试内容'))
):
    # 接口逻辑
    return {"id": id, "content": content}

修改后，接口文档中的示例值会显示为{"id": "ex_id_123", "content": "这是一段测试内容"}。

方式二：用Pydantic模型统一定义请求体 #

如果参数较多，更推荐用自定义Pydantic模型封装请求体，这种方式和你熟悉的自定义类类型设置示例的逻辑一致：

1. 定义请求体模型：

from pydantic import BaseModel, Field

class AddRequest(BaseModel):
    id: str = Field(description='this is an id', example='ex_id_123')
    content: str = Field(description='this is a content', example='这是一段测试内容')

2. 修改接口使用模型作为Body参数：

@app.post('/my_func1/add')
def func_add(request: AddRequest = Body(...)):
    # 接口逻辑
    return {"id": request.id, "content": request.content}

这种方式不仅能正常显示自定义示例，还能让代码结构更清晰，便于后续维护。

为什么直接用Body(example=...)不生效？ #

当你在接口中使用多个独立的Body参数时，FastAPI会自动创建一个匿名的Pydantic模型来整合这些参数，此时单个Body参数的example属性不会被自动合并到这个匿名模型的示例中，而通过Field定义的示例会被正确识别并应用到生成的请求体Schema里。

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