✨ Allow hiding from OpenAPI (and Swagger UI) Query, Cookie, `Head…

…er`, and `Path` parameters (#3144)

Co-authored-by: Sebastián Ramírez <tiangolo@gmail.com>

docs/en/docs/tutorial/query-params-str-validations.md

@@ -387,6 +387,22 @@ The docs will show it like this:
 
 <img src="/img/tutorial/query-params-str-validations/image01.png">
 
+## Exclude from OpenAPI
+
+To exclude a query parameter from the generated OpenAPI schema (and thus, from the automatic documentation systems), set the parameter `include_in_schema` of `Query` to `False`:
+
+=== "Python 3.6 and above"
+
+    ```Python hl_lines="10"
+    {!> ../../../docs_src/query_params_str_validations/tutorial014.py!}
+    ```
+
+=== "Python 3.10 and above"
+
+    ```Python hl_lines="7"
+    {!> ../../../docs_src/query_params_str_validations/tutorial014_py310.py!}
+    ```
+
 ## Recap
 
 You can declare additional validations and metadata for your parameters.

docs_src/query_params_str_validations/tutorial014.py

@@ -0,0 +1,15 @@
+from typing import Optional
+
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+
+@app.get("/items/")
+async def read_items(
+    hidden_query: Optional[str] = Query(None, include_in_schema=False)
+):
+    if hidden_query:
+        return {"hidden_query": hidden_query}
+    else:
+        return {"hidden_query": "Not found"}

docs_src/query_params_str_validations/tutorial014_py310.py

@@ -0,0 +1,11 @@
+from fastapi import FastAPI, Query
+
+app = FastAPI()
+
+
+@app.get("/items/")
+async def read_items(hidden_query: str | None = Query(None, include_in_schema=False)):
+    if hidden_query:
+        return {"hidden_query": hidden_query}
+    else:
+        return {"hidden_query": "Not found"}

fastapi/openapi/utils.py

@@ -92,6 +92,8 @@ def get_openapi_operation_parameters(
     for param in all_route_params:
         field_info = param.field_info
         field_info = cast(Param, field_info)
+        if not field_info.include_in_schema:
+            continue
         parameter = {
             "name": param.alias,
             "in": field_info.in_.value,

fastapi/param_functions.py

@@ -20,6 +20,7 @@ def Path(  # noqa: N802
     example: Any = Undefined,
     examples: Optional[Dict[str, Any]] = None,
     deprecated: Optional[bool] = None,
+    include_in_schema: bool = True,
     **extra: Any,
 ) -> Any:
     return params.Path(
@@ -37,6 +38,7 @@ def Path(  # noqa: N802
         example=example,
         examples=examples,
         deprecated=deprecated,
+        include_in_schema=include_in_schema,
         **extra,
     )
 
@@ -57,6 +59,7 @@ def Query(  # noqa: N802
     example: Any = Undefined,
     examples: Optional[Dict[str, Any]] = None,
     deprecated: Optional[bool] = None,
+    include_in_schema: bool = True,
     **extra: Any,
 ) -> Any:
     return params.Query(
@@ -74,6 +77,7 @@ def Query(  # noqa: N802
         example=example,
         examples=examples,
         deprecated=deprecated,
+        include_in_schema=include_in_schema,
         **extra,
     )
 
@@ -95,6 +99,7 @@ def Header(  # noqa: N802
     example: Any = Undefined,
     examples: Optional[Dict[str, Any]] = None,
     deprecated: Optional[bool] = None,
+    include_in_schema: bool = True,
     **extra: Any,
 ) -> Any:
     return params.Header(
@@ -113,6 +118,7 @@ def Header(  # noqa: N802
         example=example,
         examples=examples,
         deprecated=deprecated,
+        include_in_schema=include_in_schema,
         **extra,
     )
 
@@ -133,6 +139,7 @@ def Cookie(  # noqa: N802
     example: Any = Undefined,
     examples: Optional[Dict[str, Any]] = None,
     deprecated: Optional[bool] = None,
+    include_in_schema: bool = True,
     **extra: Any,
 ) -> Any:
     return params.Cookie(
@@ -150,6 +157,7 @@ def Cookie(  # noqa: N802
         example=example,
         examples=examples,
         deprecated=deprecated,
+        include_in_schema=include_in_schema,
         **extra,
     )
 

fastapi/params.py

@@ -31,11 +31,13 @@ def __init__(
         example: Any = Undefined,
         examples: Optional[Dict[str, Any]] = None,
         deprecated: Optional[bool] = None,
+        include_in_schema: bool = True,
         **extra: Any,
     ):
         self.deprecated = deprecated
         self.example = example
         self.examples = examples
+        self.include_in_schema = include_in_schema
         super().__init__(
             default,
             alias=alias,
@@ -75,6 +77,7 @@ def __init__(
         example: Any = Undefined,
         examples: Optional[Dict[str, Any]] = None,
         deprecated: Optional[bool] = None,
+        include_in_schema: bool = True,
         **extra: Any,
     ):
         self.in_ = self.in_
@@ -93,6 +96,7 @@ def __init__(
             deprecated=deprecated,
             example=example,
             examples=examples,
+            include_in_schema=include_in_schema,
             **extra,
         )
 
@@ -117,6 +121,7 @@ def __init__(
         example: Any = Undefined,
         examples: Optional[Dict[str, Any]] = None,
         deprecated: Optional[bool] = None,
+        include_in_schema: bool = True,
         **extra: Any,
     ):
         super().__init__(
@@ -134,6 +139,7 @@ def __init__(
             deprecated=deprecated,
             example=example,
             examples=examples,
+            include_in_schema=include_in_schema,
             **extra,
         )
 
@@ -159,6 +165,7 @@ def __init__(
         example: Any = Undefined,
         examples: Optional[Dict[str, Any]] = None,
         deprecated: Optional[bool] = None,
+        include_in_schema: bool = True,
         **extra: Any,
     ):
         self.convert_underscores = convert_underscores
@@ -177,6 +184,7 @@ def __init__(
             deprecated=deprecated,
             example=example,
             examples=examples,
+            include_in_schema=include_in_schema,
             **extra,
         )
 
@@ -201,6 +209,7 @@ def __init__(
         example: Any = Undefined,
         examples: Optional[Dict[str, Any]] = None,
         deprecated: Optional[bool] = None,
+        include_in_schema: bool = True,
         **extra: Any,
     ):
         super().__init__(
@@ -218,6 +227,7 @@ def __init__(
             deprecated=deprecated,
             example=example,
             examples=examples,
+            include_in_schema=include_in_schema,
             **extra,
         )