chore: add more docs

Author: Michael Brewer

aws_lambda_powertools/utilities/data_classes/api_gateway_authorizer_event.py

@@ -437,7 +437,7 @@ def allow_all_routes(self):
         """Adds a '*' allow to the policy to authorize access to all methods of an API"""
         self._add_route("Allow", HttpVerb.ALL, "*", [])
 
-    def deny_all_route(self):
+    def deny_all_routes(self):
         """Adds a '*' allow to the policy to deny access to all methods of an API"""
         self._add_route("Deny", HttpVerb.ALL, "*", [])
 

docs/utilities/data_classes.md

@@ -59,6 +59,7 @@ Same example as above, but using the `event_source` decorator
 
 Event Source | Data_class
 ------------------------------------------------- | ---------------------------------------------------------------------------------
+[API Gateway Authorizer](#api-gateway-authorizer) | `APIGatewayAuthorizerRequestEvent`
 [API Gateway Authorizer V2](#api-gateway-authorizer-v2) | `APIGatewayAuthorizerEventV2`
 [API Gateway Proxy](#api-gateway-proxy) | `APIGatewayProxyEvent`
 [API Gateway Proxy V2](#api-gateway-proxy-v2) | `APIGatewayProxyEventV2`
@@ -82,6 +83,87 @@ Event Source | Data_class
     The examples provided below are far from exhaustive - the data classes themselves are designed to provide a form of
     documentation inherently (via autocompletion, types and docstrings).
 
+### API Gateway Authorizer
+
+> New in 1.20.0
+
+It is used for API Gateway Rest API lambda authorizer payload. See docs on
+[Use API Gateway Lambda authorizers](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html){target="_blank"}
+for more details. Use `APIGatewayAuthorizerRequestEvent` for type "REQUEST" and `APIGatewayAuthorizerTokenEvent` for
+type "TOKEN".
+
+Below is 2 examples of a Rest API lambda authorizer. One looking up user details by `Authorization` header and using
+`APIGatewayAuthorizerResponse` to return the declined response when user is not found or authorized and include
+the user details in the request context and full access for admin users. And another using
+`APIGatewayAuthorizerTokenEvent` to get the `authorization_token`.
+
+=== "app_type_request.py"
+
+    ```python
+    from aws_lambda_powertools.utilities.data_classes import event_source
+    from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import (
+        APIGatewayAuthorizerRequestEvent,
+        APIGatewayAuthorizerResponse,
+        HttpVerb,
+    )
+    from secrets import compare_digest
+
+
+    def get_user_by_token(token):
+        if compare_digest(token, "admin-foo"):
+            return {"isAdmin": True, "name": "Admin"}
+        elif compare_digest(token, "regular-foo"):
+            return {"name": "Joe"}
+        else:
+            return None
+
+
+    @event_source(data_class=APIGatewayAuthorizerRequestEvent)
+    def handler(event: APIGatewayAuthorizerRequestEvent, context):
+        user = get_user_by_token(event.get_header_value("Authorization"))
+
+        # parse the `methodArn` as an `APIGatewayRouteArn`
+        arn = event.parsed_arn
+        # Create the response builder from parts of the `methodArn`
+        builder = APIGatewayAuthorizerResponse("user", arn.region, arn.aws_account_id, arn.api_id, arn.stage)
+
+        if user is None:
+            # No user was found, so we return not authorized
+            builder.deny_all_routes()
+            return builder.asdict()
+
+        # Found the user and setting the details in the context
+        builder.context = user
+
+        # Conditional IAM Policy
+        if user.get("isAdmin", False):
+            builder.allow_all_routes()
+        else:
+            builder.allow_route(HttpVerb.GET, "/user-profile")
+
+        return builder.asdict()
+    ```
+=== "app_type_token.py"
+
+    ```python
+    from aws_lambda_powertools.utilities.data_classes import event_source
+    from aws_lambda_powertools.utilities.data_classes.api_gateway_authorizer_event import (
+        APIGatewayAuthorizerTokenEvent,
+        APIGatewayAuthorizerResponse,
+    )
+
+
+    @event_source(data_class=APIGatewayAuthorizerTokenEvent)
+    def handler(event: APIGatewayAuthorizerTokenEvent, context):
+        arn = event.parsed_arn
+        builder = APIGatewayAuthorizerResponse("user", arn.region, arn.aws_account_id, arn.api_id, arn.stage)
+        if event.authorization_token == "42":
+            builder.allow_all_methods()
+        else:
+            builder.deny_all_methods()
+        return builder.asdict()
+    ```
+
 ### API Gateway Authorizer V2
 
 > New in 1.20.0
@@ -103,10 +185,13 @@ the user details in the request context.
         APIGatewayAuthorizerEventV2,
         APIGatewayAuthorizerResponseV2,
     )
+    from secrets import compare_digest
 
 
     def get_user_by_token(token):
-        ...
+        if compare_digest(token, "Foo"):
+            return {"name": "Foo"}
+        return None
 
 
     @event_source(data_class=APIGatewayAuthorizerEventV2)

tests/functional/data_classes/test_api_gateway_authorizer.py

@@ -61,7 +61,7 @@ def test_authorizer_response_allow_all_routes_with_context():
 
 
 def test_authorizer_response_deny_all_routes(builder: APIGatewayAuthorizerResponse):
-    builder.deny_all_route()
+    builder.deny_all_routes()
     assert builder.asdict() == {
         "principalId": "foo",
         "policyDocument": {