Python FastApi（8）：模式的额外信息、额外数据类型

1 模式的额外信息

        您可以在JSON模式中定义额外的信息。一个常见的用例是添加一个将在文档中显示的example。有几种方法可以声明额外的 JSON 模式信息。

1.1 Pydantic schema_extra

        您可以使用 Config 和 schema_extra 为Pydantic模型声明一个示例，这些额外的信息将按原样添加到输出的JSON模式中。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()


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

    model_config = {
        "json_schema_extra": {
            "examples": [
                {
                    "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

1.2 Field 的附加参数

        在 Field, Path, Query, Body 和其他之后将会看到的工厂函数，你可以为JSON 模式声明额外信息，你也可以通过给工厂函数传递其他的任意参数来给JSON 模式声明额外信息，比如增加 example:

from fastapi import FastAPI
from pydantic import BaseModel, Field

app = FastAPI()


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

        传递的那些额外参数不会添加任何验证，只会添加注释，用于文档的目的。

1.3 Body 额外参数

        你可以通过传递额外信息给 Field 同样的方式操作Path, Query, Body等。比如，你可以将请求体的一个 example 传递给 Body:

from typing import Annotated

from fastapi import Body, FastAPI
from pydantic import BaseModel

app = FastAPI()


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


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

1.4 查看文档

        使用上面的任何方法，它在 /docs 中看起来都是这样的:

2 额外数据类型

2.1 额外数据类型

        到目前为止，您一直在使用常见的数据类型，如:

• int
• float
• str
• bool

        也可以使用更复杂的数据类型。仍然会拥有现在已经看到的相同的特性:

• 传入请求的数据转换。
• 响应数据转换。
• 数据验证。
• 自动补全和文档。

2.2 其他数据类型

        下面是一些你可以使用的其他数据类型:

• UUID:
  • 一种标准的 "通用唯一标识符" ，在许多数据库和系统中用作ID。
  • 在请求和响应中将以 str 表示。
• datetime.datetime:
  • 一个 Python datetime.datetime.
  • 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15T15:53:00+05:00.
• datetime.date:
  • Python datetime.date.
  • 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 2008-09-15.
• datetime.time:
  • 一个 Python datetime.time.
  • 在请求和响应中将表示为 ISO 8601 格式的 str ，比如: 14:23:55.003.
• datetime.timedelta:
  • 一个 Python datetime.timedelta.
  • 在请求和响应中将表示为 float 代表总秒数。
  • Pydantic 也允许将其表示为 "ISO 8601 时间差异编码", 查看文档了解更多信息。
• frozenset:
  • 在请求和响应中，作为 set 对待：
    • 在请求中，列表将被读取，消除重复，并将其转换为一个 set。
    • 在响应中 set 将被转换为 list 。
    • 产生的模式将指定那些 set 的值是唯一的 (使用 JSON 模式的 uniqueItems)。
• bytes:
  • 标准的 Python bytes。
  • 在请求和响应中被当作 str 处理。
  • 生成的模式将指定这个 str 是 binary "格式"。
• Decimal:
  • 标准的 Python Decimal。
  • 在请求和响应中被当做 float 一样处理。

2.3 例子

        下面是一个路径操作的示例，其中的参数使用了上面的一些类型。

from datetime import datetime, time, timedelta
from typing import Annotated
from uuid import UUID

from fastapi import Body, FastAPI

app = FastAPI()


@app.put("/items/{item_id}")
async def read_items(
        item_id: UUID,
        start_datetime: Annotated[datetime, Body()],
        end_datetime: Annotated[datetime, Body()],
        process_after: Annotated[timedelta, Body()],
        repeat_at: Annotated[time | None, Body()] = None,
):
    start_process = start_datetime + process_after
    duration = end_datetime - start_process
    return {
        "item_id": item_id,
        "start_datetime": start_datetime,
        "end_datetime": end_datetime,
        "process_after": process_after,
        "repeat_at": repeat_at,
        "start_process": start_process,
        "duration": duration,
    }

        注意，函数内的参数有原生的数据类型，你可以执行正常的操作，如执行日期操作:

from datetime import datetime, time, timedelta
from typing import Annotated
from uuid import UUID

from fastapi import Body, FastAPI

app = FastAPI()


@app.put("/items/{item_id}")
async def read_items(
    item_id: UUID,
    start_datetime: Annotated[datetime, Body()],
    end_datetime: Annotated[datetime, Body()],
    process_after: Annotated[timedelta, Body()],
    repeat_at: Annotated[time | None, Body()] = None,
):
    start_process = start_datetime + process_after
    duration = end_datetime - start_process
    return {
        "item_id": item_id,
        "start_datetime": start_datetime,
        "end_datetime": end_datetime,
        "process_after": process_after,
        "repeat_at": repeat_at,
        "start_process": start_process,
        "duration": duration,
    }