From 977162a862d1baeb19c19f569bd2e18b38921422 Mon Sep 17 00:00:00 2001
From: Heitor Lessa <lessa@amazon.co.uk>
Date: Tue, 28 Sep 2021 10:00:02 +0200
Subject: [PATCH] docs(event-handler): document catch-all routes (#705)

---
 docs/core/event_handler/api_gateway.md | 38 ++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md
index 76a72fd03c..aeaa75e0d2 100644
--- a/docs/core/event_handler/api_gateway.md
+++ b/docs/core/event_handler/api_gateway.md
@@ -287,6 +287,8 @@ You can use `/path/{dynamic_value}` when configuring dynamic URL paths. This all
     }
     ```
 
+#### Nested routes
+
 You can also nest paths as configured earlier in [our sample infrastructure](#required-resources): `/{message}/{name}`.
 
 === "app.py"
@@ -323,6 +325,42 @@ You can also nest paths as configured earlier in [our sample infrastructure](#re
     }
     ```
 
+#### Catch-all routes
+
+!!! note "We recommend having explicit routes whenever possible; use catch-all routes sparingly"
+
+You can use a regex string to handle an arbitrary number of paths within a request, for example `.+`.
+
+You can also combine nested paths with greedy regex to catch in between routes.
+
+!!! warning "We will choose the more explicit registered route that match incoming event"
+
+=== "app.py"
+
+    ```python hl_lines="5"
+    from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver
+
+    app = ApiGatewayResolver()
+
+    @app.get(".+")
+    def catch_any_route_after_any():
+        return {"path_received": app.current_event.path}
+
+    def lambda_handler(event, context):
+        return app.resolve(event, context)
+    ```
+
+=== "sample_request.json"
+
+    ```json
+    {
+        "resource": "/any/route/should/work",
+        "path": "/any/route/should/work",
+        "httpMethod": "GET",
+        ...
+    }
+    ```
+
 ### Accessing request details
 
 By integrating with [Data classes utilities](../../utilities/data_classes.md){target="_blank"}, you have access to request details, Lambda context and also some convenient methods.