mirror of https://github.com/tiangolo/fastapi.git
docs: clarify misleading 'Required, can be None' section in query param validation
This commit is contained in:
parent
f2687dc1bb
commit
882fa913da
|
|
@ -246,11 +246,34 @@ So, when you need to declare a value as required while using `Query`, you can si
|
||||||
|
|
||||||
### Required, can be `None` { #required-can-be-none }
|
### Required, can be `None` { #required-can-be-none }
|
||||||
|
|
||||||
You can declare that a parameter can accept `None`, but that it's still required. This would force clients to send a value, even if the value is `None`.
|
You might want to declare that a parameter can accept `None`, but is still required.
|
||||||
|
|
||||||
To do that, you can declare that `None` is a valid type but simply do not declare a default value:
|
However, because of how **HTTP query parameters** work, clients cannot actually send a real `None` (or `null`) value — query parameters are always sent as **strings**.
|
||||||
|
That means you cannot truly have a *required* parameter that also allows a real `None` value.
|
||||||
|
|
||||||
{* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *}
|
For example, you might try:
|
||||||
|
|
||||||
|
```Python
|
||||||
|
q: Annotated[str | None, Query(min_length=3)] = ...
|
||||||
|
```
|
||||||
|
|
||||||
|
But this will still expect a string value, and if the client omits q or tries to send q=None, FastAPI will raise a validation error.
|
||||||
|
In other words, None is not an acceptable runtime value for query parameters — only strings are.
|
||||||
|
|
||||||
|
If you want to accept special values (like "None" or an empty string) and interpret them as None in your application, you can handle them manually in your function:
|
||||||
|
|
||||||
|
```Python
|
||||||
|
from fastapi import FastAPI, Query
|
||||||
|
from typing import Annotated
|
||||||
|
|
||||||
|
app = FastAPI()
|
||||||
|
|
||||||
|
@app.get("/items/")
|
||||||
|
async def read_items(q: Annotated[str | None, Query()] = ...):
|
||||||
|
if q in ("None", "", "null"):
|
||||||
|
q = None
|
||||||
|
return {"q": q}
|
||||||
|
```
|
||||||
|
|
||||||
## Query parameter list / multiple values { #query-parameter-list-multiple-values }
|
## Query parameter list / multiple values { #query-parameter-list-multiple-values }
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue