fastapi 模式的额外信息，示例 / Cookie参数 / Header参数

文章目录

1. Pydantic schema_extra
2. Field 的附加参数
3. Body 额外参数
4. Cookie 参数
5. Header 参数
- 5.1 重复的 headers

learn from https://fastapi.tiangolo.com/zh/tutorial/schema-extra-example/

添加一个将在文档中显示的 example

1. Pydantic schema_extra

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel
app = FastAPI()class Item(BaseModel):name: strdescription: Optional[str] = Noneprice: floattax: Optional[float] = Noneclass Config:schema_extra = {"example": {"name": "michael","description": "a learner","price": 100.0, "tax": 0.1}}@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):res = {"item_id": item_id, "item": item}return res

来看看文档：http://127.0.0.1:8000/docs#/default/update_item_items__item_id__put

其中： class Config:
schema_extra = {
“example”: {

加黑的字符，大小写必须完全一致，应该是内置的字段，否则无法显示例子

2. Field 的附加参数

Field(None, example=xxx)

from typing import Optional
from fastapi import FastAPI
from pydantic import BaseModel, Field
app = FastAPI()class Item(BaseModel):name: str = Field(..., example="michael")description: Optional[str] = Field(None, example="handsome")price: float = Field(..., example=34.5)tax: Optional[float] = Field(None, example=0.1)@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item):res = {"item_id": item_id, "item": item}return res

3. Body 额外参数

可以通过传递额外信息给 Field 同样的方式操作Path, Query, Body等

from typing import Optional
from fastapi import FastAPI, Body
from pydantic import BaseModel, Field
app = FastAPI()class Item(BaseModel):name: strdescription: Optional[str] = Noneprice: floattax: Optional[float] = None@app.put("/items/{item_id}")
async def update_item(item_id: int, item: Item = Body(...,example = {  # 加入 example 参数"name": "michael","description": "a learner","price": 100.1, "tax": 0.1})
):res = {"item_id": item_id, "item": item}return res

4. Cookie 参数

声明 Cookie 参数的结构与声明 Query 参数和 Path 参数时相同。

第一个值是参数的默认值，同时也可以传递所有验证参数或注释参数，来校验参数

你需要使用 Cookie 来声明 cookie 参数，否则参数将会被解释为 查询参数

from typing import Optional
from fastapi import Cookie, FastAPIapp = FastAPI()
@app.get("/items/")
async def read_items(ads_id: Optional[str] = Cookie(None)):return {"ads_id": ads_id}

使用 postman 测试

5. Header 参数

大多数标准的 headers 用 "连字符" 分隔，也称为 "减号" (-)。

但是像 user-agent 这样的变量在Python中是无效的。

因此, 默认情况下, Header 将把参数名称的字符从下划线 (_) 转换为连字符 (-) 来提取并记录 headers

如果需要禁用 下划线到连字符 的自动转换，设置 Header 的参数 convert_underscores 为 False
注意：一些 HTTP 代理和服务器不允许使用带有下划线的 headers

from typing import Optional
from fastapi import Cookie, FastAPI, Headerapp = FastAPI()
@app.get("/items/")
async def read_items(my_agent: Optional[str] = Header(None)):return {"my_agent": my_agent}

禁用下划线自动转换 strange_header: Optional[str] = Header(None, convert_underscores=False)

from typing import Optional
from fastapi import Cookie, FastAPI, Headerapp = FastAPI()
@app.get("/items/")
async def read_items(my_agent: Optional[str] = Header(None, convert_underscores=False)):return {"my_agent": my_agent}

5.1 重复的 headers

可以通过一个Python list 的形式获得重复header 的 所有值

from typing import Optional, List
from fastapi import Cookie, FastAPI, Headerapp = FastAPI()
@app.get("/items/")
async def read_items(x_token: Optional[List[str]] = Header(None)):return {"x_token value:": x_token}