Skip to content

Commit f3de704

Browse files
rubenfonsecarubenfonseca
authored
docs(event_handler): add bedrock agent resolver documentation (aws-powertools#3602)
1 parent bc5db0a commit f3de704

33 files changed

+1562
-147
lines changed

‎aws_lambda_powertools/event_handler/bedrock_agent.py

Lines changed: 163 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
11
from re import Match
2-
from typing import Any, Dict
2+
from typing import Any, Callable, Dict, List, Optional
33

44
from typing_extensions import override
55

66
from aws_lambda_powertools.event_handler import ApiGatewayResolver
77
from aws_lambda_powertools.event_handler.api_gateway import (
8+
_DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
89
ProxyEventType,
910
ResponseBuilder,
1011
)
12+
from aws_lambda_powertools.event_handler.openapi.types import OpenAPIResponse
1113
from aws_lambda_powertools.utilities.data_classes import BedrockAgentEvent
1214

1315

@@ -83,6 +85,166 @@ def __init__(self, debug: bool = False, enable_validation: bool = True):
8385
)
8486
self._response_builder_class = BedrockResponseBuilder
8587

88+
# Note: we need ignore[override] because we are making the optional `description` field required.
89+
@override
90+
def get( # type: ignore[override]
91+
self,
92+
rule: str,
93+
description: str,
94+
cors: Optional[bool] = None,
95+
compress: bool = False,
96+
cache_control: Optional[str] = None,
97+
summary: Optional[str] = None,
98+
responses: Optional[Dict[int, OpenAPIResponse]] = None,
99+
response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
100+
tags: Optional[List[str]] = None,
101+
operation_id: Optional[str] = None,
102+
include_in_schema: bool = True,
103+
middlewares: Optional[List[Callable[..., Any]]] = None,
104+
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
105+
return super(BedrockAgentResolver, self).get(
106+
rule,
107+
cors,
108+
compress,
109+
cache_control,
110+
summary,
111+
description,
112+
responses,
113+
response_description,
114+
tags,
115+
operation_id,
116+
include_in_schema,
117+
middlewares,
118+
)
119+
120+
# Note: we need ignore[override] because we are making the optional `description` field required.
121+
@override
122+
def post( # type: ignore[override]
123+
self,
124+
rule: str,
125+
description: str,
126+
cors: Optional[bool] = None,
127+
compress: bool = False,
128+
cache_control: Optional[str] = None,
129+
summary: Optional[str] = None,
130+
responses: Optional[Dict[int, OpenAPIResponse]] = None,
131+
response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
132+
tags: Optional[List[str]] = None,
133+
operation_id: Optional[str] = None,
134+
include_in_schema: bool = True,
135+
middlewares: Optional[List[Callable[..., Any]]] = None,
136+
):
137+
return super().post(
138+
rule,
139+
cors,
140+
compress,
141+
cache_control,
142+
summary,
143+
description,
144+
responses,
145+
response_description,
146+
tags,
147+
operation_id,
148+
include_in_schema,
149+
middlewares,
150+
)
151+
152+
# Note: we need ignore[override] because we are making the optional `description` field required.
153+
@override
154+
def put( # type: ignore[override]
155+
self,
156+
rule: str,
157+
description: str,
158+
cors: Optional[bool] = None,
159+
compress: bool = False,
160+
cache_control: Optional[str] = None,
161+
summary: Optional[str] = None,
162+
responses: Optional[Dict[int, OpenAPIResponse]] = None,
163+
response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
164+
tags: Optional[List[str]] = None,
165+
operation_id: Optional[str] = None,
166+
include_in_schema: bool = True,
167+
middlewares: Optional[List[Callable[..., Any]]] = None,
168+
):
169+
return super().put(
170+
rule,
171+
cors,
172+
compress,
173+
cache_control,
174+
summary,
175+
description,
176+
responses,
177+
response_description,
178+
tags,
179+
operation_id,
180+
include_in_schema,
181+
middlewares,
182+
)
183+
184+
# Note: we need ignore[override] because we are making the optional `description` field required.
185+
@override
186+
def patch( # type: ignore[override]
187+
self,
188+
rule: str,
189+
description: str,
190+
cors: Optional[bool] = None,
191+
compress: bool = False,
192+
cache_control: Optional[str] = None,
193+
summary: Optional[str] = None,
194+
responses: Optional[Dict[int, OpenAPIResponse]] = None,
195+
response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
196+
tags: Optional[List[str]] = None,
197+
operation_id: Optional[str] = None,
198+
include_in_schema: bool = True,
199+
middlewares: Optional[List[Callable]] = None,
200+
):
201+
return super().patch(
202+
rule,
203+
cors,
204+
compress,
205+
cache_control,
206+
summary,
207+
description,
208+
responses,
209+
response_description,
210+
tags,
211+
operation_id,
212+
include_in_schema,
213+
middlewares,
214+
)
215+
216+
# Note: we need ignore[override] because we are making the optional `description` field required.
217+
@override
218+
def delete( # type: ignore[override]
219+
self,
220+
rule: str,
221+
description: str,
222+
cors: Optional[bool] = None,
223+
compress: bool = False,
224+
cache_control: Optional[str] = None,
225+
summary: Optional[str] = None,
226+
responses: Optional[Dict[int, OpenAPIResponse]] = None,
227+
response_description: str = _DEFAULT_OPENAPI_RESPONSE_DESCRIPTION,
228+
tags: Optional[List[str]] = None,
229+
operation_id: Optional[str] = None,
230+
include_in_schema: bool = True,
231+
middlewares: Optional[List[Callable[..., Any]]] = None,
232+
):
233+
return super().delete(
234+
rule,
235+
cors,
236+
compress,
237+
cache_control,
238+
summary,
239+
description,
240+
responses,
241+
response_description,
242+
tags,
243+
operation_id,
244+
include_in_schema,
245+
middlewares,
246+
)
247+
86248
@override
87249
def _convert_matches_into_route_keys(self, match: Match) -> Dict[str, str]:
88250
# In Bedrock Agents, all the parameters come inside the "parameters" key, not on the apiPath

‎docs/core/event_handler/_openapi_customization_metadata.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
<!-- markdownlint-disable MD041 MD043 -->
2+
3+
Defining and customizing OpenAPI metadata gives detailed, top-level information about your API. Here's the method to set and tailor this metadata:
4+
5+
| Field Name | Type | Description |
6+
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7+
| `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. |
8+
| `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. |
9+
| `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. |
10+
| `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. |
11+
| `description` | `str` | A verbose description that can include Markdown formatting, providing a full explanation of the API's purpose, functionalities, and general usage instructions. |
12+
| `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. |
13+
| `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. |
14+
| `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. |
15+
| `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. |
16+
| `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

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<!-- markdownlint-disable MD041 MD043 -->
2+
3+
Customize your API endpoints by adding metadata to endpoint definitions.
4+
5+
Here's a breakdown of various customizable fields:
6+
7+
| Field Name | Type | Description |
8+
| ---------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9+
| `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. |
10+
| `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. |
11+
| `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. |
12+
| `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. |
13+
| `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. |
14+
| `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. |
15+
| `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

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
<!-- markdownlint-disable MD041 MD043 -->
2+
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:
3+
4+
| Field name | Type | Description |
5+
|-----------------------|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
6+
| `alias` | `str` | Alternative name for a field, used when serializing and deserializing data |
7+
| `validation_alias` | `str` | Alternative name for a field during validation (but not serialization) |
8+
| `serialization_alias` | `str` | Alternative name for a field during serialization (but not during validation) |
9+
| `description` | `str` | Human-readable description |
10+
| `gt` | `float` | Greater than. If set, value must be greater than this. Only applicable to numbers |
11+
| `ge` | `float` | Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers |
12+
| `lt` | `float` | Less than. If set, value must be less than this. Only applicable to numbers |
13+
| `le` | `float` | Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers |
14+
| `min_length` | `int` | Minimum length for strings |
15+
| `max_length` | `int` | Maximum length for strings |
16+
| `pattern` | `string` | A regular expression that the string must match. |
17+
| `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 |
18+
| `multiple_of` | `float` | Value must be a multiple of this. Only applicable to numbers |
19+
| `allow_inf_nan` | `bool` | Allow `inf`, `-inf`, `nan`. Only applicable to numbers |
20+
| `max_digits` | `int` | Maximum number of allow digits for strings |
21+
| `decimal_places` | `int` | Maximum number of decimal places allowed for numbers |
22+
| `examples` | `List[Any]` | List of examples of the field |
23+
| `deprecated` | `bool` | Marks the field as deprecated |
24+
| `include_in_schema` | `bool` | If `False` the field will not be part of the exported OpenAPI schema |
25+
| `json_schema_extra` | `JsonDict` | Any additional JSON schema data for the schema property |

0 commit comments

Comments
 (0)