1. 基础配置方法
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| from pydantic import BaseModel
class Item(BaseModel):
name: str
description: str | None = None
price: float
class Config:
schema_extra = {
"example": {
"name": "Foo",
"description": "A very nice Item",
"price": 35.4
}
}
|
- 通过模型内部定义
Config类实现
schema_extra字段用于添加扩展信息- 示例数据会显示在API文档的Schema部分
2. 字段级别示例
1
2
3
4
5
6
| from pydantic import Field
class Item(BaseModel):
name: str = Field(example="Foo")
description: str | None = Field(default=None, example="A very nice Item")
price: float = Field(example=35.4)
|
- 使用
Field参数直接为字段添加示例
- 示例会显示在对应字段的文档说明中
- 支持同时定义默认值和示例数据
3. 多示例配置
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
| from fastapi import Body
@app.put("/items/{item_id}")
async def update_item(
item_id: int,
item: Item = Body(
examples={
"normal": {
"summary": "正常示例",
"value": {
"name": "Foo",
"price": 35.4
}
},
"invalid": {
"summary": "无效数据示例",
"value": {
"name": "Bar",
"price": "thirty"
}
}
}
)
):
...
|
- 使用
Body()的examples参数定义多个示例
- 支持添加示例说明（summary字段）
- 多个示例会分组显示在API文档中
- 示例类型支持有效/无效数据演示
4. 注意事项
examples参数会覆盖schema_extra的示例配置- 字段示例和模型示例可以组合使用
- 支持OpenAPI规范的所有示例配置选项
- 示例数据不会影响实际的数据验证逻辑
根据OpenAPI规范，所有示例配置最终都会体现在API文档中，帮助开发者更好地理解接口的使用方式。