diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 4765b36cbe..7b6d4422cd 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -222,12 +222,24 @@ So, when you need to declare a value as required while using `Query`, you can si ### 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 can declare that a parameter can accept `None`, but that it's still required. This forces clients to send the parameter, even if the value is `None` or `null`. -To do that, you can declare that `None` is a valid type but simply do not declare a default value: +In FastAPI, a parameter is required when it has no default value. Using `...` as the default value also marks it as required. + +At the same time, if the type annotation includes `None`, like `str | None`, the parameter is nullable and can accept `None`. + +So, with `Annotated[str | None, Query(min_length=3)] = ...`, the client must send the parameter, but the value can still be `None`: {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} +/// tip + +If you use `None` as the default value, for example `q: Annotated[str | None, Query(min_length=3)] = None`, the parameter becomes optional. + +If you use `...` as the default value, for example `q: Annotated[str | None, Query(min_length=3)] = ...`, the parameter remains required even though the type allows `None`. + +/// + ## Query parameter list / multiple values { #query-parameter-list-multiple-values } When you define a query parameter explicitly with `Query` you can also declare it to receive a list of values, or said in another way, to receive multiple values. diff --git a/docs_src/query_params_str_validations/tutorial006c_an_py310.py b/docs_src/query_params_str_validations/tutorial006c_an_py310.py index 2995d9c979..1ab0a7d53d 100644 --- a/docs_src/query_params_str_validations/tutorial006c_an_py310.py +++ b/docs_src/query_params_str_validations/tutorial006c_an_py310.py @@ -6,7 +6,7 @@ app = FastAPI() @app.get("/items/") -async def read_items(q: Annotated[str | None, Query(min_length=3)]): +async def read_items(q: Annotated[str | None, Query(min_length=3)] = ...): results = {"items": [{"item_id": "Foo"}, {"item_id": "Bar"}]} if q: results.update({"q": q})