docs(event_handler): add bedrock agent resolver documentation (#3602)

aws_lambda_powertools/event_handler/bedrock_agent.py

@@ -1,13 +1,15 @@
 from re import Match
-from typing import Any, Dict
+from typing import Any, Callable, Dict, List, Optional
 
 from typing_extensions import override
 
 from aws_lambda_powertools.event_handler import ApiGatewayResolver
 from aws_lambda_powertools.event_handler.api_gateway import (
+    _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
     ProxyEventType,
     ResponseBuilder,
 )
+from aws_lambda_powertools.event_handler.openapi.types import OpenAPIResponse
 from aws_lambda_powertools.utilities.data_classes import BedrockAgentEvent
 
 
@@ -83,6 +85,166 @@ def __init__(self, debug: bool = False, enable_validation: bool = True):
         )
         self._response_builder_class = BedrockResponseBuilder
 
+    # Note: we need ignore[override] because we are making the optional `description` field required.
+    @override
+    def get(  # type: ignore[override]
+        self,
+        rule: str,
+        description: str,
+        cors: Optional[bool] = None,
+        compress: bool = False,
+        cache_control: Optional[str] = None,
+        summary: Optional[str] = None,
+        responses: Optional[Dict[int, OpenAPIResponse]] = None,
+        response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
+        tags: Optional[List[str]] = None,
+        operation_id: Optional[str] = None,
+        include_in_schema: bool = True,
+        middlewares: Optional[List[Callable[..., Any]]] = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        return super(BedrockAgentResolver, self).get(
+            rule,
+            cors,
+            compress,
+            cache_control,
+            summary,
+            description,
+            responses,
+            response_description,
+            tags,
+            operation_id,
+            include_in_schema,
+            middlewares,
+        )
+
+    # Note: we need ignore[override] because we are making the optional `description` field required.
+    @override
+    def post(  # type: ignore[override]
+        self,
+        rule: str,
+        description: str,
+        cors: Optional[bool] = None,
+        compress: bool = False,
+        cache_control: Optional[str] = None,
+        summary: Optional[str] = None,
+        responses: Optional[Dict[int, OpenAPIResponse]] = None,
+        response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
+        tags: Optional[List[str]] = None,
+        operation_id: Optional[str] = None,
+        include_in_schema: bool = True,
+        middlewares: Optional[List[Callable[..., Any]]] = None,
+    ):
+        return super().post(
+            rule,
+            cors,
+            compress,
+            cache_control,
+            summary,
+            description,
+            responses,
+            response_description,
+            tags,
+            operation_id,
+            include_in_schema,
+            middlewares,
+        )
+
+    # Note: we need ignore[override] because we are making the optional `description` field required.
+    @override
+    def put(  # type: ignore[override]
+        self,
+        rule: str,
+        description: str,
+        cors: Optional[bool] = None,
+        compress: bool = False,
+        cache_control: Optional[str] = None,
+        summary: Optional[str] = None,
+        responses: Optional[Dict[int, OpenAPIResponse]] = None,
+        response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
+        tags: Optional[List[str]] = None,
+        operation_id: Optional[str] = None,
+        include_in_schema: bool = True,
+        middlewares: Optional[List[Callable[..., Any]]] = None,
+    ):
+        return super().put(
+            rule,
+            cors,
+            compress,
+            cache_control,
+            summary,
+            description,
+            responses,
+            response_description,
+            tags,
+            operation_id,
+            include_in_schema,
+            middlewares,
+        )
+
+    # Note: we need ignore[override] because we are making the optional `description` field required.
+    @override
+    def patch(  # type: ignore[override]
+        self,
+        rule: str,
+        description: str,
+        cors: Optional[bool] = None,
+        compress: bool = False,
+        cache_control: Optional[str] = None,
+        summary: Optional[str] = None,
+        responses: Optional[Dict[int, OpenAPIResponse]] = None,
+        response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
+        tags: Optional[List[str]] = None,
+        operation_id: Optional[str] = None,
+        include_in_schema: bool = True,
+        middlewares: Optional[List[Callable]] = None,
+    ):
+        return super().patch(
+            rule,
+            cors,
+            compress,
+            cache_control,
+            summary,
+            description,
+            responses,
+            response_description,
+            tags,
+            operation_id,
+            include_in_schema,
+            middlewares,
+        )
+
+    # Note: we need ignore[override] because we are making the optional `description` field required.
+    @override
+    def delete(  # type: ignore[override]
+        self,
+        rule: str,
+        description: str,
+        cors: Optional[bool] = None,
+        compress: bool = False,
+        cache_control: Optional[str] = None,
+        summary: Optional[str] = None,
+        responses: Optional[Dict[int, OpenAPIResponse]] = None,
+        response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
+        tags: Optional[List[str]] = None,
+        operation_id: Optional[str] = None,
+        include_in_schema: bool = True,
+        middlewares: Optional[List[Callable[..., Any]]] = None,
+    ):
+        return super().delete(
+            rule,
+            cors,
+            compress,
+            cache_control,
+            summary,
+            description,
+            responses,
+            response_description,
+            tags,
+            operation_id,
+            include_in_schema,
+            middlewares,
+        )
+
     @override
     def _convert_matches_into_route_keys(self, match: Match) -> Dict[str, str]:
         # In Bedrock Agents, all the parameters come inside the "parameters" key, not on the apiPath

docs/core/event_handler/_openapi_customization_metadata.md

@@ -0,0 +1,16 @@
+<!-- markdownlint-disable MD041 MD043 -->
+
+Defining and customizing OpenAPI metadata gives detailed, top-level information about your API. Here's the method to set and tailor this metadata:
+
+| Field Name         | Type           | Description                                                                                                                                                                         |
+| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`            | `str`          | The title for your API. It should be a concise, specific name that can be used to identify the API in documentation or listings.                                                    |
+| `version`          | `str`          | The version of the API you are documenting. This could reflect the release iteration of the API and helps clients understand the evolution of the API.                              |
+| `openapi_version`  | `str`          | Specifies the version of the OpenAPI Specification on which your API is based. When using Pydantic v1 it defaults to 3.0.3, and when using Pydantic v2, it defaults to 3.1.0.       |
+| `summary`          | `str`          | A short and informative summary that can provide an overview of what the API does. This can be the same as or different from the title but should add context or information.       |
+| `description`      | `str`          | A verbose description that can include Markdown formatting, providing a full explanation of the API's purpose, functionalities, and general usage instructions.                     |
+| `tags`             | `List[str]`    | A collection of tags that categorize endpoints for better organization and navigation within the documentation. This can group endpoints by their functionality or other criteria.  |
+| `servers`          | `List[Server]` | An array of Server objects, which specify the URL to the server and a description for its environment (production, staging, development, etc.), providing connectivity information. |
+| `terms_of_service` | `str`          | A URL that points to the terms of service for your API. This could provide legal information and user responsibilities related to the usage of the API.                             |
+| `contact`          | `Contact`      | A Contact object containing contact details of the organization or individuals maintaining the API. This may include fields such as name, URL, and email.                           |
+| `license_info`     | `License`      | A License object providing the license details for the API, typically including the name of the license and the URL to the full license text.                                       |

docs/core/event_handler/_openapi_customization_operations.md

@@ -0,0 +1,15 @@
+<!-- markdownlint-disable MD041 MD043 -->
+
+Customize your API endpoints by adding metadata to endpoint definitions.
+
+Here's a breakdown of various customizable fields:
+
+| Field Name             | Type                                    | Description                                                                                                                                                                                                                                                                                                                |
+| ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `summary`              | `str`                                   | A concise overview of the main functionality of the endpoint. This brief introduction is usually displayed in autogenerated API documentation and helps consumers quickly understand what the endpoint does.                                                                                                               |
+| `description`          | `str`                                   | A more detailed explanation of the endpoint, which can include information about the operation's behavior, including side effects, error states, and other operational guidelines.                                                                                                                                         |
+| `responses`            | `Dict[int, Dict[str, OpenAPIResponse]]` | A dictionary that maps each HTTP status code to a Response Object as defined by the [OpenAPI Specification](https://swagger.io/specification/#response-object). This allows you to describe expected responses, including default or error messages, and their corresponding schemas or models for different status codes. |
+| `response_description` | `str`                                   | Provides the default textual description of the response sent by the endpoint when the operation is successful. It is intended to give a human-readable understanding of the result.                                                                                                                                       |
+| `tags`                 | `List[str]`                             | Tags are a way to categorize and group endpoints within the API documentation. They can help organize the operations by resources or other heuristic.                                                                                                                                                                      |
+| `operation_id`         | `str`                                   | A unique identifier for the operation, which can be used for referencing this operation in documentation or code. This ID must be unique across all operations described in the API.                                                                                                                                       |
+| `include_in_schema`    | `bool`                                  | A boolean value that determines whether or not this operation should be included in the OpenAPI schema. Setting it to `False` can hide the endpoint from generated documentation and schema exports, which might be useful for private or experimental endpoints.                                                          |

docs/core/event_handler/_openapi_customization_parameters.md

@@ -0,0 +1,25 @@
+<!-- markdownlint-disable MD041 MD043 -->
+Whenever you use OpenAPI parameters to validate [query strings](api_gateway.md#validating-query-strings) or [path parameters](api_gateway.md#validating-path-parameters), you can enhance validation and OpenAPI documentation by using any of these parameters:
+
+| Field name            | Type        | Description                                                                                                                                                                |
+|-----------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `alias`               | `str`       | Alternative name for a field, used when serializing and deserializing data                                                                                                 |
+| `validation_alias`    | `str`       | Alternative name for a field during validation (but not serialization)                                                                                                     |
+| `serialization_alias` | `str`       | Alternative name for a field during serialization (but not during validation)                                                                                              |
+| `description`         | `str`       | Human-readable description                                                                                                                                                 |
+| `gt`                  | `float`     | Greater than. If set, value must be greater than this. Only applicable to numbers                                                                                          |
+| `ge`                  | `float`     | Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers                                                                     |
+| `lt`                  | `float`     | Less than. If set, value must be less than this. Only applicable to numbers                                                                                                |
+| `le`                  | `float`     | Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers                                                                           |
+| `min_length`          | `int`       | Minimum length for strings                                                                                                                                                 |
+| `max_length`          | `int`       | Maximum length for strings                                                                                                                                                 |
+| `pattern`             | `string`    | A regular expression that the string must match.                                                                                                                           |
+| `strict`              | `bool`      | If `True`, strict validation is applied to the field. See [Strict Mode](https://docs.pydantic.dev/latest/concepts/strict_mode/){target"_blank" rel="nofollow"} for details |
+| `multiple_of`         | `float`     | Value must be a multiple of this. Only applicable to numbers                                                                                                               |
+| `allow_inf_nan`       | `bool`      | Allow `inf`, `-inf`, `nan`. Only applicable to numbers                                                                                                                     |
+| `max_digits`          | `int`       | Maximum number of allow digits for strings                                                                                                                                 |
+| `decimal_places`      | `int`       | Maximum number of decimal places allowed for numbers                                                                                                                       |
+| `examples`            | `List[Any]` | List of examples of the field                                                                                                                                              |
+| `deprecated`          | `bool`      | Marks the field as deprecated                                                                                                                                              |
+| `include_in_schema`   | `bool`      | If `False` the field will not be part of the exported OpenAPI schema                                                                                                       |
+| `json_schema_extra`   | `JsonDict`  | Any additional JSON schema data for the schema property                                                                                                                    |