FastAPI 学习之路（十二）接口几个额外信息和额外数据类型

系列文章：

一、额外信息

我们有这样的一个需求，我们希望可以看到接口的一个简单的请求示例展示在我们的接口文档中，应该如何实现呢。我们看下如何实现的：

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": "DEMO",
                "description": "DEMO",
                "price": 20,
                "tax": 0.5,
            }
        }
@app.post("/items/")
def return_item( item: Item):
    results = { "item": item}
    return results

那么我们请求下试试。

接口满足我们的请求，我们看下接口文档是否有请求的示例。

接口文档是正常有这个的示例。代码中使用Config 和 schema_extra 为Pydantic模型声明一个简单的示例。

其实我们在Field也会可以实现一个额外的信息，比如我们增加一个example字段，我们看下如何实现的，带来什么样的效果

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel,Field
app = FastAPI()
class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price:float = Field(..., example=600)
    tax: Optional[float] = Field(None, example=0.5)

@app.post("/items/")
def return_item( item: Item):
    results = { "item": item}
    return results

我们看下效果，正常的接口请求没有变动。

我们看下接口的文档。文档在解析的时候，会解析出来这个额外的信息。

当然像Body，Path等也都可以增加这些参数。

二、额外数据类型

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

int
float
str
bool

但是您也可以使用更复杂的数据类型。

您仍然会拥有现在已经看到的相同的特性:

很棒的编辑器支持。
传入请求的数据转换。
响应数据转换。
数据验证。
自动补全和文档。

其他数据类型

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

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 将被转换为 list 。
产生的模式将指定那些 set 的值是唯一的 (使用 JSON 模式的 uniqueItems)。
在请求和响应中，作为 set 对待：

bytes:

标准的 Python bytes。
在请求和相应中被当作 str 处理。
生成的模式将指定这个 str 是 binary "格式"。

Decimal:

标准的 Python Decimal。
在请求和相应中被当做 float 一样处理。

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

from typing import Optional
from uuid import UUID
from fastapi import Body, FastAPI
from datetime import datetime, time, timedelta
app = FastAPI()
@app.put("/items/{id}")
async def read_items(
    item_id: UUID,
    start_time: Optional[datetime] = Body(None),

    end_time: Optional[datetime] = Body(None),


    after: Optional[timedelta] = Body(None),

):
    start_process = start_time 
    duration = end_time - start_process
    return {
        "id": item_id,
        "start_datetime": start_time,
        "end_datetime": end_time,
        "after": after,
        "start_process": start_process,
        "duration": duration,
    }