可以为路径参数添加额外的校验和元数据,跟 Query 的参数是一毛一样的
Path 也可以添加元数据相关信息,这些信息将包含在生成的 OpenAPI 中,并由文档用户界面和外部工具使用
# 别名
alias: Optional[str] = None
# 标题
title: Optional[str] = None
# 描述
description: Optional[str] = None
# 是否弃用
deprecated: Optional[bool] = None
from fastapi import FastAPI, Path
from typing import Optional
import uvicorn
app = FastAPI()
# 元数据
@app.get("/items/{item_id}")
async def read_items(
item_id: Optional[str] = Path(
default=...,
min_length=2,
max_length=50,
regex="^菠萝$",
title="标题",
description="很长很长的描述",
deprecated=True,
)
):
return {"item_id": item_id}
...
因为路径参数并不能通过 参数名=value 的形式来传值,所以没有办法通过 alias = value 的方式给别名传值,最终将会报错
@app.get("/alias/{item_id}")
async def read_items(
item_id: Optional[str] = Path(
default=...,
alias="item_alias"
)
):
return {"item_id": item_id}
直接在 Swagger API 文档上尝试运行也会报错,所以路径参数不要用别名哦!
Python 会将 item_id: int = Path(...) 识别为默认参数,而 q: str 是位置参数,而位置参数不能在默认参数后面,所以爆红了
在 Python 3.8 新除了仅限关键字参数:https://cloud.tencent.com/developer/article/1858741
@app.get("/item/{item_id}")
async def read_items(
*,
item_id: int = Path(...),
name: str):
return {"item_id": item_id, "name": name}
将 * 作为第一个参数,那么 * 后面的所有参数都会当做关键字参数处理,即使它们没有设置默认值(像 name)
Query 和 Path 都可以添加数字校验,Query 文章并没有讲解数字校验,所以这里重点讲下
# 大于
gt: Optional[float] = None
# 大于等于
ge: Optional[float] = None
# 小于
lt: Optional[float] = None
# 小于等于
le: Optional[float] = None
@app.get("/number/{item_id}")
async def read_items(
*,
item_id: int = Path(..., title="The IDsss", gt=10, le=20),
name: str = None):
return {"item_id": item_id, "name": name}
@app.get("/path_query/{item_id}")
async def read_items(
*,
item_id: int = Path(..., description="path", ge=1, lt=5, example=1),
name: str,
age: float = Query(..., description="query", gt=0.0, le=10)):
return {"item_id": item_id, "age": age, "name": name}
数字校验也可以适用于 float 类型的值
这里的 item_id 还加了个 example 参数,就是个示例值,所以在接口文档中会显示 Example