docs: complete extending middlewares section

Signed-off-by: heitorlessa <lessa@amazon.co.uk>

Author: heitorlessa

docs/core/event_handler/api_gateway.md

@@ -539,7 +539,21 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth
 
 #### Extending middlewares
 
-!!! todo "Explain how to create a middleware that accepts configuration with `BaseMiddlewareHandler`"
+You can implement `BaseMiddlewareHandler` interface to create middlewares that accept configuration, or perform complex operations (_see [being a good citizen section](#being-a-good-citizen)_).
+
+As a practical example, let's refactor our correlation ID middleware so it accepts a custom HTTP Header to look for.
+
+```python hl_lines="5 11 23 36" title="Authoring class-based middlewares with BaseMiddlewareHandler"
+--8<-- "examples/event_handler_rest/src/middleware_extending_middlewares.py"
+```
+
+1. You can add any constructor argument like you normally would
+2. We implement `handler` just like we [did before](#middleware) with the only exception of the `self` argument, since it's a method.
+3. Get response from the next middleware (if any) or from `/todos` route.
+4. Register an instance of `CorrelationIdMiddleware`.
+
+!!! note "Class-based **vs** function-based middlewares"
+    When registering a middleware, we expect a callable in both cases. For class-based middlewares, `BaseMiddlewareHandler` is doing the work of calling your `handler` method with the correct parameters, hence why we expect an instance of it.
 
 #### Being a good citizen
 

examples/event_handler_rest/src/middleware_extending_middlewares.py

@@ -0,0 +1,47 @@
+import requests
+
+from aws_lambda_powertools import Logger
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response
+from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, NextMiddleware
+
+app = APIGatewayRestResolver()
+logger = Logger()
+
+
+class CorrelationIdMiddleware(BaseMiddlewareHandler):
+    def __init__(self, header: str):  # (1)!
+        """Extract and inject correlation ID in response
+
+        Parameters
+        ----------
+        header : str
+            HTTP Header to extract correlation ID
+        """
+        super().__init__()
+        self.header = header
+
+    def handler(self, app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response:  # (2)!
+        request_id = app.current_event.request_context.request_id
+        correlation_id = app.current_event.get_header_value(
+            name=self.header,
+            default_value=request_id,
+        )
+
+        response = next_middleware(app)  # (3)!
+        response.headers[self.header] = correlation_id
+
+        return response
+
+
+@app.get("/todos", middlewares=[CorrelationIdMiddleware(header="x-correlation-id")])  # (4)!
+def get_todos():
+    todos: requests.Response = requests.get("https://jsonplaceholder.typicode.com/todos")
+    todos.raise_for_status()
+
+    # for brevity, we'll limit to the first 10 only
+    return {"todos": todos.json()[:10]}
+
+
+@logger.inject_lambda_context
+def lambda_handler(event, context):
+    return app.resolve(event, context)