diff --git a/docs/en/docs/img/tutorial/query-params/image01.png b/docs/en/docs/img/tutorial/query-params/image01.png new file mode 100644 index 0000000000..6222a9aef3 Binary files /dev/null and b/docs/en/docs/img/tutorial/query-params/image01.png differ diff --git a/docs/en/docs/tutorial/query-params.md b/docs/en/docs/tutorial/query-params.md index 0b74b10f81..0ed34c9983 100644 --- a/docs/en/docs/tutorial/query-params.md +++ b/docs/en/docs/tutorial/query-params.md @@ -223,3 +223,45 @@ In this case, there are 3 query parameters: !!! tip You could also use `Enum`s the same way as with [Path Parameters](path-params.md#predefined-values){.internal-link target=_blank}. + +## Free Form Query Parameters + +Sometimes you want to receive some query parameters, but you don't know in advance what they will be. **FastAPI** supports this case too. + +=== "Python 3.10+" + + ```Python hl_lines="8" + {!> ../../../docs_src/query_params/tutorial007_py310.py!} + ``` + +And when you open your browser at http://127.0.0.1:8000/docs, you will that OpenAPI supports this too: + + + +However, since the query parameters are decaled in the request as + +``` +http://127.0.0.1:8000/query/mixed-type-params?query=1&foo=bar&foo=baz +``` + +**FastAPI** greedily adds all the query parameters to every `Query` argument for which it is valid. The above request will be parsed as: + +```Python +{ + "query": 1, + "string_mapping": { + "query": "1", + "foo": "baz" + }, + "mapping_query_int": { + "query": 1 + }, + "sequence_mapping_queries": { + "query": [ + "1" + ], + "foo": [] + } +} +``` +As you can see the `query` parameter is added to every `Query` argument for which it is valid. This is because **FastAPI** does not know which `Query` argument you want to add the `query` parameter to, and `1` validates as an `int`, `str`, and `List[str]`. `foo` is only added to the `string_mapping` and `sequence_mapping_queries` arguments because it is not a valid `int`. \ No newline at end of file diff --git a/docs_src/query_params/tutorial007_py310.py b/docs_src/query_params/tutorial007_py310.py new file mode 100644 index 0000000000..d8a9f50793 --- /dev/null +++ b/docs_src/query_params/tutorial007_py310.py @@ -0,0 +1,20 @@ +from typing import Mapping, List + +from fastapi import FastAPI, Query + +app = FastAPI() + + +@app.get("/query/mixed-type-params") +def get_mixed_mapping_mixed_type_query_params( + query: int = Query(), + mapping_query_str: Mapping[str, str] = Query({}), + mapping_query_int: Mapping[str, int] = Query({}), + sequence_mapping_queries: Mapping[str, List[int]] = Query({}), +): + return { + "query":query, + "string_mapping": mapping_query_str, + "mapping_query_int": mapping_query_int, + "sequence_mapping_queries": sequence_mapping_queries + }