feat(openapi): add option to exclude parameter from schema (#4177)

* feat(openapi): added option to exclude parameter from schema (#4173)

* feat(openapi): fixed condition in test

* Update litestar/params.py

Co-authored-by: Janek Nouvertné <provinzkraut@posteo.de>

* Update litestar/params.py

Co-authored-by: Janek Nouvertné <provinzkraut@posteo.de>

* feat(openapi): fixed docstring

---------

Co-authored-by: Janek Nouvertné <provinzkraut@posteo.de>

Author: mmev

litestar/_openapi/parameters.py

@@ -194,13 +194,15 @@ def create_parameters_for_field_definitions(self, fields: dict[str, FieldDefinit
         )
 
         for field_name, field_definition in unique_handler_fields:
-            if (
-                isinstance(field_definition.kwarg_definition, DependencyKwarg)
-                and field_name not in self.dependency_providers
-            ):
+            kwarg_definition = field_definition.kwarg_definition
+            if isinstance(kwarg_definition, DependencyKwarg) and field_name not in self.dependency_providers:
                 # never document explicit dependencies
                 continue
 
+            if isinstance(kwarg_definition, ParameterKwarg) and not kwarg_definition.include_in_schema:
+                # exclude parameters that are marked as not included in the schema
+                continue
+
             if provider := self.dependency_providers.get(field_name):
                 self.create_parameters_for_field_definitions(fields=provider.parsed_fn_signature.parameters)
             else:

litestar/params.py

@@ -124,6 +124,11 @@ class KwargDefinition:
     Use as the key for the reference when creating a component for this type
     .. versionadded:: 2.12.0
     """
+    include_in_schema: bool = True
+    """
+    A boolean flag dictating whether this parameter should be included in the schema.
+    .. versionadded:: 2.17.0
+    """
 
     @property
     def is_constrained(self) -> bool:
@@ -201,6 +206,7 @@ def Parameter(
     title: str | None = None,
     schema_extra: dict[str, Any] | None = None,
     schema_component_key: str | None = None,
+    include_in_schema: bool = True,
 ) -> Any:
     """Create an extended parameter kwarg definition.
 
@@ -247,6 +253,7 @@ def Parameter(
             .. versionadded:: 2.8.0
         schema_component_key: Use this as the key for the reference when creating a component for this type
             .. versionadded:: 2.12.0
+        include_in_schema: A boolean flag dictating whether this parameter should be included in the schema.
     """
     return ParameterKwarg(
         annotation=annotation,
@@ -273,6 +280,7 @@ def Parameter(
         pattern=pattern,
         schema_extra=schema_extra,
         schema_component_key=schema_component_key,
+        include_in_schema=include_in_schema,
     )
 
 

tests/unit/test_openapi/test_parameters.py

@@ -475,3 +475,33 @@ def handler(
         "allowEmptyValue": False,
         "allowReserved": False,
     }
+
+
+def test_not_included_in_schema_parameter() -> None:
+    @get("/handler")
+    async def handler(param: Annotated[str, Parameter(include_in_schema=False)]) -> None:
+        pass
+
+    with create_test_client(handler) as client:
+        response = client.get("/schema/openapi.json")
+
+        response_json = response.json()
+        handler_schema = response_json["paths"]["/handler"]["get"]
+        assert "parameters" not in handler_schema
+
+
+def test_two_parameters_but_one_not_included_in_schema() -> None:
+    @get("/handler")
+    def handler(param1: str, param2: str = Parameter(include_in_schema=False)) -> None:
+        pass
+
+    with create_test_client(handler) as client:
+        response = client.get("/schema/openapi.json")
+
+        response_json = response.json()
+        handler_schema = response_json["paths"]["/handler"]["get"]
+        assert "parameters" in handler_schema
+
+        parameter_names = {param["name"] for param in handler_schema["parameters"]}
+        assert "param1" in parameter_names
+        assert "param2" not in parameter_names

tests/unit/test_params.py

@@ -294,3 +294,42 @@ def test_optional_query_parameter_consistency_with_default_queried_with_other_pa
     assert optional_default_client.get("/optional-default", params={"param": "a"}).json() == {"key": None}
     assert optional_default_client.get("/optional-annotated-default", params={"abc": "xyz"}).json() == {"key": None}
     assert optional_default_client.get("/optional-annotated-default", params={"param": "a"}).json() == {"key": None}
+
+
+def test_not_included_in_schema_param_as_annotated() -> None:
+    @get(path="/")
+    def handler(param: Annotated[str, Parameter(include_in_schema=True)]) -> str:
+        return param
+
+    with create_test_client(handler) as client:
+        response = client.get("/")
+        assert response.status_code == HTTP_400_BAD_REQUEST
+
+        response = client.get("/?param=a")
+        assert response.status_code == HTTP_200_OK
+        assert response.text == "a"
+
+
+def test_not_included_in_schema_param_as_default() -> None:
+    @get(path="/")
+    def handler(param: str = Parameter(include_in_schema=True)) -> str:
+        return param
+
+    with create_test_client(handler) as client:
+        response = client.get("/")
+        assert response.status_code == HTTP_400_BAD_REQUEST
+
+        response = client.get("/?param=a")
+        assert response.status_code == HTTP_200_OK
+        assert response.text == "a"
+
+
+def test_not_included_in_schema_param_with_default_value() -> None:
+    @get(path="/")
+    def handler(param: str = Parameter(default="b", include_in_schema=True)) -> str:
+        return param
+
+    with create_test_client(handler) as client:
+        response = client.get("/")
+        assert response.status_code == HTTP_200_OK
+        assert response.text == "b"