网页
综合
更新时间 2026-11-17 03:06:01
Query Parameter Models - FastAPI
自动蜘蛛
fastapi.tiangolo.com
正文约 3204 字
Use the official FastAPI skill for your installed version. Install it from your project directory:
See Develop with AI.
If you have a group of query parameters that are related, you can create a Pydantic model to declare them.
This would allow you to re-use the model in multiple places and also to declare validations and metadata for all the parameters at once. 😎
This is supported since FastAPI version 0.115.0. 🤓
Declare the query parameters that you need in a Pydantic model, and then declare the parameter as Query:
Prefer to use the Annotated version if possible.
FastAPI will extract the data for each field from the query parameters in the request and give you the Pydantic model you defined.
You can see the query parameters in the docs UI at /docs:
In some special use cases (probably not very common), you might want to restrict the query parameters that you want to receive.
You can use Pydantic's model configuration to forbid any extra fields:
Prefer to use the Annotated version if possible.
If a client tries to send some extra data in the query parameters, they will receive an error response.
For example, if the client tries to send a tool query parameter with a value of plumbus, like:
They will receive an error response telling them that the query parameter tool is not allowed:
You can declare multiple query parameter models, and combine them with individual query parameters or dependencies.
Prefer to use the Annotated version if possible.
The request parameters stay at the same level.
There are no pagination or filters keys in the query string. Each model validates the query parameters independently, with its own defaults, field validators, and model validators. The same applies when the models or individual parameters are declared in dependencies.
If models share a parameter name or alias, each model validates that request parameter independently. Use distinct names or aliases for independent values. OpenAPI lists a shared parameter once, as it does for parameters shared with dependencies, so shared declarations should describe the same type and constraints.
Each model's extra configuration applies to all query parameters, including those declared in other models or dependencies. With extra="forbid", any parameter outside that model is rejected. With extra="allow", those parameters are included as model extras.
This also works for Header and Cookie models.
Declare a query parameter model with | None and a default of None to make the group optional.
Prefer to use the Annotated version if possible.
If neither start nor end is sent, date_range is None. If either is sent, FastAPI validates the model and requires both fields.
Using | None without a default still makes the parameter required.
Extra parameters follow the model's extra configuration. Ignored extras do not make the model present.
OpenAPI lists the group's fields individually and marks them as optional.
You can also declare optional header parameter models and cookie parameter models.
You can use Pydantic models to declare query parameters in FastAPI. 😎
Spoiler alert: you can also use Pydantic models to declare cookies and headers, but you will read about that later in the tutorial. 🤫
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。