Schema Extra - Example

Schema Extra - Example

可以为 JSON 模式定义额外的信息

一个常见的用法是为 api 文档添加一个例子

有如下的几种方式来定义额外的 JSON 模式信息

Pydantic schema_extra

可以通过使用 Config 和 schema_extra 为 Pydantic 模型声明例子

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None

    class Config:
        schema_extra = {
            "example": {
                "name": "Foo",
                "description": "A very nice Item",
                "price": 35.4,
                "tax": 3.2,
            }
        }


@app.put("/items/{item_id}")
async def update_item(*, item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

这些额外的信息会被添加到 api 文档的 example value 中

Field additional arguments

在 Field，Path 等，可以通过 example 参数来添加例子

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(..., example="Foo")
    description: str = Field(None, example="A very nice Item")
    price: float = Field(..., example=35.4)
    tax: float = Field(None, example=3.2)


@app.put("/items/{item_id}")
async def update_item(*, item_id: int, item: Item):
    results = {"item_id": item_id, "item": item}
    return results

注：这些额外的参数只是用来为帮助文档添加注释，并不会有任何验证的功能

Body additional arguments

同 Field 的用法一样，也可以对 Path， Query，Body 中添加例子

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: str = None
    price: float
    tax: float = None


@app.put("/items/{item_id}")
async def update_item(
    *,
    item_id: int,
    item: Item = Body(
        ...,
        example={
            "name": "Foo",
            "description": "A very nice Item",
            "price": 35.4,
            "tax": 3.2,
        },
    )
):
    results = {"item_id": item_id, "item": item}
    return results

技术细节

JSON 协议中在最近的版本中定义了 examples 字段，但是 OpenAPI 基于老版本的 JSON，因此没有 examples 字段

OpenAPI 通过定义 example 实现和 JSON 类似的功能，这也是帮助文档界面所使用的

其他信息

可以用相同的方式为 JSON 模式添加额外信息，例如自定义前端UI