FastAPI教程 模式的額外信息 - 例子

您可以在JSON模式中定義額外的信息。

一個(gè)常見(jiàn)的用例是添加一個(gè)將在文檔中顯示的example。

有幾種方法可以聲明額外的 JSON 模式信息。

Pydantic schema_extra

您可以使用 Config 和 schema_extra 為Pydantic模型聲明一個(gè)示例，如Pydantic 文檔：定制 Schema 中所述:

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[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

這些額外的信息將按原樣添加到輸出的JSON模式中。

Field 的附加參數(shù)

在 Field, Path, Query, Body 和其他你之后將會(huì)看到的工廠函數(shù)，你可以為JSON 模式聲明額外信息，你也可以通過(guò)給工廠函數(shù)傳遞其他的任意參數(shù)來(lái)給JSON 模式聲明額外信息，比如增加 example:

from typing import Optional

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


class Item(BaseModel):
    name: str = Field(..., example="Foo")
    description: Optional[str] = Field(None, example="A very nice Item")
    price: float = Field(..., example=35.4)
    tax: Optional[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

Warning

請(qǐng)記住，傳遞的那些額外參數(shù)不會(huì)添加任何驗(yàn)證，只會(huì)添加注釋?zhuān)糜谖臋n的目的。

Body 額外參數(shù)

你可以通過(guò)傳遞額外信息給 Field 同樣的方式操作Path, Query, Body等。

比如，你可以將請(qǐng)求體的一個(gè) example 傳遞給 Body:

from typing import Optional

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float
    tax: Optional[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

文檔 UI 中的例子

使用上面的任何方法，它在 /docs 中看起來(lái)都是這樣的:

技術(shù)細(xì)節(jié)

關(guān)于 example 和 examples...

JSON Schema在最新的一個(gè)版本中定義了一個(gè)字段 examples ，但是 OpenAPI 基于之前的一個(gè)舊版JSON Schema，并沒(méi)有 examples.

所以 OpenAPI為了相似的目的定義了自己的 example (使用 example, 而不是 examples), 這也是文檔 UI 所使用的 (使用 Swagger UI).

所以，雖然 example 不是JSON Schema的一部分，但它是OpenAPI的一部分，這將被文檔UI使用。

其他信息

同樣的方法，你可以添加你自己的額外信息，這些信息將被添加到每個(gè)模型的JSON模式中，例如定制前端用戶(hù)界面，等等。