diff --git a/docs/en/docs/tutorial/query-params-str-validations.md b/docs/en/docs/tutorial/query-params-str-validations.md index 4765b36cbe..8dfd2503e4 100644 --- a/docs/en/docs/tutorial/query-params-str-validations.md +++ b/docs/en/docs/tutorial/query-params-str-validations.md @@ -222,10 +222,16 @@ 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's type can be `None`, but that it's still **required** (it must be included in the request). This is useful when you want to require the parameter to be present, but allow the value to be `None`. To do that, you can declare that `None` is a valid type but simply do not declare a default value: +/// info + +When the parameter is required (no default value), omitting it will result in a **422 Validation Error**. The `None` type is included so that the OpenAPI schema correctly represents the parameter as **nullable**, and it allows your code to handle a `None` value explicitly. However, note that there's no standard HTTP mechanism to send `None` as a query parameter value from a client. + +/// + {* ../../docs_src/query_params_str_validations/tutorial006c_an_py310.py hl[9] *} ## Query parameter list / multiple values { #query-parameter-list-multiple-values } diff --git a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py index 74c10b885d..23f5c9f9c2 100644 --- a/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py +++ b/tests/test_tutorial/test_query_params_str_validations/test_tutorial006c.py @@ -22,25 +22,36 @@ def get_client(request: pytest.FixtureRequest): return client -@pytest.mark.xfail( - reason="Code example is not valid. See https://github.com/fastapi/fastapi/issues/12419" -) def test_query_params_str_validations_no_query(client: TestClient): + """When q is required (no default), omitting it returns 422.""" response = client.get("/items/") - assert response.status_code == 200 - assert response.json() == { # pragma: no cover - "items": [{"item_id": "Foo"}, {"item_id": "Bar"}], + assert response.status_code == 422 + assert response.json() == { + "detail": [ + { + "type": "missing", + "loc": ["query", "q"], + "msg": "Field required", + "input": None, + } + ] } -@pytest.mark.xfail( - reason="Code example is not valid. See https://github.com/fastapi/fastapi/issues/12419" -) def test_query_params_str_validations_empty_str(client: TestClient): + """Empty string fails min_length validation.""" response = client.get("/items/?q=") - assert response.status_code == 200 - assert response.json() == { # pragma: no cover - "items": [{"item_id": "Foo"}, {"item_id": "Bar"}], + assert response.status_code == 422 + assert response.json() == { + "detail": [ + { + "type": "string_too_short", + "loc": ["query", "q"], + "msg": "String should have at least 3 characters", + "input": "", + "ctx": {"min_length": 3}, + } + ] }