Adding docs + small fix in tests

Author: leandrodamascena

docs/core/event_handler/api_gateway.md

@@ -11,6 +11,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Load Balanc
 * Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer
 * Built-in integration with [Event Source Data Classes utilities](../../utilities/data_classes.md){target="_blank"} for self-documented event schema
 * Works with micro function (one or a few routes) and monolithic functions (all routes)
+* Support for Middleware
 * Support for OpenAPI schema generation
 * Support data validation for requests/responses
 
@@ -303,7 +304,7 @@ If you need to accept multiple HTTP methods in a single function, or support a H
 
     For brevity, we'll focus on Pydantic only.
 
-All resolvers can optionally coerce and validate incoming requests by setting `enable_validation=True`.
+All resolvers can optionally coerce and validate incoming requests by setting `enable_validation=True`. You can use Pydantic models to validate request bodies, query strings, headers, and form parameters.
 
 With this feature, we can now express how we expect our incoming data and response to look like. This moves data validation responsibilities to Event Handler resolvers, reducing a ton of boilerplate code.
 
@@ -519,6 +520,16 @@ In the following example, we use a new `Query` OpenAPI type to add [one out of m
 
     1. `example_multi_value_param` is a list containing values from the `ExampleEnum` enumeration.
 
+=== "validating_query_string_with_pydantic.py"
+
+    You can use Pydantic models to define your query string parameters.
+
+    ```python hl_lines="18-22 27"
+    --8<-- "examples/event_handler_rest/src/validating_query_string_with_pydantic.py"
+    ```
+
+    1. `todo` is a Pydantic model.
+
 <!-- markdownlint-enable MD013 -->
 
 #### Validating path parameters
@@ -567,6 +578,16 @@ In the following example, we use a new `Header` OpenAPI type to add [one out of
 
     1. `cloudfront_viewer_country` is a list that must contain values from the `CountriesAllowed` enumeration.
 
+=== "validating_headers_with_pydantic.py"
+
+    You can use Pydantic models to define your headers parameters.
+
+    ```python hl_lines="18-22 27"
+    --8<-- "examples/event_handler_rest/src/validating_headers_with_pydantic.py"
+    ```
+
+    1. `todo` is a Pydantic model.
+
 #### Handling form data
 
 !!! info "You must set `enable_validation=True` to handle file uploads and form data via type annotation."

examples/event_handler_rest/src/validating_headers_with_pydantic.py

@@ -0,0 +1,33 @@
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.params import Header
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver(enable_validation=True)
+
+
+class Todo(BaseModel):
+    userId: int
+    id_: Optional[int] = Field(alias="id", default=None)
+    title: str
+    completed: bool
+
+
+@app.get("/todos")
+@tracer.capture_method
+def get_todos(todo: Annotated[Todo, Header()]) -> Dict[str, Any]:  # (1)!
+    return todo.model_dump()
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_HTTP)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

examples/event_handler_rest/src/validating_query_string_with_pydantic.py

@@ -0,0 +1,33 @@
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+from typing_extensions import Annotated
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.params import Query
+from aws_lambda_powertools.logging import correlation_paths
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = APIGatewayRestResolver(enable_validation=True)
+
+
+class Todo(BaseModel):
+    userId: int
+    id_: Optional[int] = Field(alias="id", default=None)
+    title: str
+    completed: bool
+
+
+@app.get("/todos")
+@tracer.capture_method
+def get_todos(todo: Annotated[Todo, Query()]) -> Dict[str, Any]:  # (1)!
+    return todo.model_dump()
+
+
+@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_HTTP)
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext) -> dict:
+    return app.resolve(event, context)

tests/functional/event_handler/_pydantic/test_openapi_validation_middleware.py

@@ -3,10 +3,10 @@
 from dataclasses import dataclass
 from enum import Enum
 from pathlib import PurePath
-from typing import Dict, List, Literal, Optional, Tuple, Union
+from typing import Any, Dict, List, Literal, Optional, Tuple, Union
 
 import pytest
-from pydantic import BaseModel, Field
+from pydantic import AfterValidator, Base64UrlStr, BaseModel, ConfigDict, Field, StringConstraints, alias_generators
 from typing_extensions import Annotated
 
 from aws_lambda_powertools.event_handler import (
@@ -2542,15 +2542,11 @@ def create_action(action: Annotated[action_type, Body()]):
 
 def test_validate_pydantic_query_params_with_config_dict_and_validators(gw_event):
     """Test that Pydantic models with ConfigDict, aliases, and validators work correctly"""
-    from typing import Any
-
-    from pydantic import AfterValidator, Base64UrlStr, ConfigDict, StringConstraints, alias_generators
 
     del gw_event["multiValueHeaders"]
     del gw_event["multiValueQueryStringParameters"]
 
     app = APIGatewayRestResolver(enable_validation=True)
-    app.enable_swagger(path="/swagger")
 
     def _validate_powertools(value: str) -> str:
         if not value.startswith("Powertools"):