在 FastAPI 中,Query
类用于定义查询参数,并提供了多种参数来限制和描述这些参数。以下是一些常用的参数,它们可以用来限制和描述 Query
类的实例:
-
default:
- 描述:设置参数的默认值。
- 类型:任何类型。
- 示例:
default=None
-
alias:
- 描述:为参数设置一个别名,这在 URL 中使用的名称与函数参数名称不一致时非常有用。
- 类型:
str
- 示例:
alias="my_alias"
-
title:
- 描述:为参数设置一个标题,这通常用于 API 文档。
- 类型:
str
- 示例:
title="User ID"
-
description:
- 描述:为参数提供一个描述,这在 API 文档中显示,有助于说明参数的用途。
- 类型:
str
- 示例:
description="The ID of the user"
-
gt (greater than):
- 描述:参数值必须大于指定的值。
- 类型:
float
或int
- 示例:
gt=0
-
lt (less than):
- 描述:参数值必须小于指定的值。
- 类型:
float
或int
- 示例:
lt=100
-
ge (greater than or equal to):
- 描述:参数值必须大于或等于指定的值。
- 类型:
float
或int
- 示例:
ge=0
-
le (less than or equal to):
- 描述:参数值必须小于或等于指定的值。
- 类型:
float
或int
- 示例:
le=100
-
min_length:
- 描述:参数的最小长度(对于字符串)。
- 类型:
int
- 示例:
min_length=1
-
max_length:
- 描述:参数的最大长度(对于字符串)。
- 类型:
int
- 示例:
max_length=50
-
regex:
- 描述:参数值必须匹配指定的正则表达式。
- 类型:
str
- 示例:
regex="^[a-zA-Z0-9]+$"
-
example:
- 描述:为参数提供一个示例值,这在 API 文档中显示。
- 类型:任何类型。
- 示例:
example=10
这些参数可以帮助你定义查询参数的预期行为,同时提供额外的验证和文档说明。使用这些参数可以确保客户端发送的数据符合你的 API 的要求,并且可以自动生成清晰、有用的 API 文档。
为查询参数添加额外的校验和元数据,例如:
from fastapi import FastAPI, Query
from typing import Union
app = FastAPI()
@app.get("/items/")
async def read_items(
q: Union[str, None] = Query(default=None, min_length=3, max_length=50, regex="^fixedquery$")
):
results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]}
if q:
results.update({"q": q})
return results
在这个例子中,q 参数被定义为一个字符串,它有一个最小长度、最大长度和一个正则表达式模式。如果 q 参数的值不满足这些条件,FastAPI 将返回一个错误响应,并且这些验证规则会被自动记录在 API 文档中。
此外,Query 类还可以处理接收多个值的查询参数,例如:
from typing import List
@app.get("/items/")
async def read_items(q: List[str] = Query(default=["foo", "bar"], alias="query")):
return {"queries": q}
在这个例子中,q 参数被定义为一个列表,它可以接收多个值,并且可以通过 alias 参数为它设置一个别名。