AWS powertools documentation change
Summary
Major restructuring of the API Gateway documentation: removed detailed OpenAPI customization sections (parameters, operations, metadata, Swagger UI, security schemes, extensions) and moved them to a dedicated OpenAPI page. Added comprehensive new sections on Dependency Injection, Router usage, custom serializers/deserializers, and updated examples. Updated table of contents and added Lambda Features section.
Security assessment
The changes are primarily a documentation reorganization and feature addition. There is no evidence of addressing a specific security vulnerability, incident, or weakness. The removal of security schemes documentation is part of moving OpenAPI details to a separate page, not a security fix. The new dependency injection feature includes authentication examples but is a feature addition, not a security patch.
Diff
diff --git a/powertools/python/latest/core/event_handler/api_gateway.md b/powertools/python/latest/core/event_handler/api_gateway.md index 5c5fefc97..be0637f3e 100644 --- a//powertools/python/latest/core/event_handler/api_gateway.md +++ b//powertools/python/latest/core/event_handler/api_gateway.md @@ -102,6 +101,0 @@ Metrics - * Customizing OpenAPI parameters - * Customizing API operations - * Customizing OpenAPI metadata - * Customizing Swagger UI - * Security schemes - * OpenAPI extensions @@ -114,0 +109,6 @@ Metrics + * Dependency injection + * Basic usage + * Nested dependencies + * Accessing the request + * Combining middleware and Depends() + * Testing with dependency overrides @@ -119,0 +120 @@ Metrics + * [ OpenAPI ](../openapi/) @@ -137,0 +139,5 @@ Metrics + * [ Lambda Features ](../../../lambda-features/) + +Lambda Features + * [ Lambda Managed Instances ](../../../lambda-features/managed-instances/) + * [ Durable Functions ](../../../lambda-features/durable-functions/) @@ -280,6 +285,0 @@ Table of contents - * Customizing OpenAPI parameters - * Customizing API operations - * Customizing OpenAPI metadata - * Customizing Swagger UI - * Security schemes - * OpenAPI extensions @@ -292,0 +293,6 @@ Table of contents + * Dependency injection + * Basic usage + * Nested dependencies + * Accessing the request + * Combining middleware and Depends() + * Testing with dependency overrides @@ -3567 +3573 @@ We use the `Annotated` type to tell the Event Handler that a particular paramete -In the following example, we use a new `Query` OpenAPI type to add one out of many possible constraints, which should read as: +In the following example, we use a new `Query` OpenAPI type to add [one out of many possible constraints](../openapi/#customizing-parameters), which should read as: @@ -3945 +3951 @@ You can use Pydantic models to define your query string parameters. -Just like we learned in query string validation, we can use a new `Path` OpenAPI type to add constraints. +Just like we learned in query string validation, we can use a new `Path` OpenAPI type to [add constraints](../openapi/#customizing-parameters). @@ -4043 +4049 @@ We use the `Annotated` type to tell the Event Handler that a particular paramete -In the following example, we use a new `Header` OpenAPI type to add one out of many possible constraints, which should read as: +In the following example, we use a new `Header` OpenAPI type to add [one out of many possible constraints](../openapi/#customizing-parameters), which should read as: @@ -5342,3 +5348 @@ Raising common HTTP Status errors (4xx, 5xx) -This feature requires data validation feature to be enabled. - -Behind the scenes, the data validation feature auto-generates an OpenAPI specification from your routes and type annotations. You can use [Swagger UI](https://swagger.io/tools/swagger-ui/) to visualize and interact with your newly auto-documented API. +OpenAPI documentation has moved @@ -5346 +5350 @@ Behind the scenes, the data validation feature auto-generates an OpenAPI specifi -There are some important **caveats** that you should know before enabling it: +For complete OpenAPI documentation including Swagger UI customization, security schemes, and OpenAPI Merge for micro-functions, see the dedicated [OpenAPI documentation](../openapi/). @@ -5348,7 +5352 @@ There are some important **caveats** that you should know before enabling it: -Caveat | Description ----|--- -Swagger UI is **publicly accessible by default** | When using `enable_swagger` method, you can protect sensitive API endpoints by implementing a custom middleware using your preferred authorization mechanism. -**No micro-functions support** yet | Swagger UI is enabled on a per resolver instance which will limit its accuracy here. -You need to expose a **new route** | You'll need to expose the following path to Lambda: `/swagger`; ignore if you're routing this path already. -JS and CSS files are **embedded within Swagger HTML** | If you are not using an external CDN to serve Swagger UI assets, we embed JS and CSS directly into the HTML. To enhance performance, please consider enabling the `compress` option to minimize the size of HTTP requests. -Authorization data is **lost** on browser close/refresh | Use `enable_swagger(persist_authorization=True)` to persist authorization data, like OAuath 2.0 access tokens. +Use `enable_swagger()` to serve interactive API documentation: @@ -5446,8 +5443,0 @@ enabling_swagger.py - 1. `enable_swagger` creates a route to serve Swagger UI and allows quick customizations. - -You can also include middlewares to protect or enhance the overall experience. - - - -Here's an example of what it looks like by default: - @@ -7548 +7538 @@ Enabling debug mode -When you enable Data Validation, we use a combination of Pydantic Models and [OpenAPI](https://www.openapis.org/) type annotations to add constraints to your API's parameters. +OpenAPI documentation has moved @@ -7550 +7540 @@ When you enable Data Validation, we use a combination of Pydantic Models and [Op -OpenAPI schema version depends on the installed version of Pydantic +For complete OpenAPI documentation including customization, security schemes, extensions, and OpenAPI Merge for micro-functions, see the dedicated [OpenAPI documentation](../openapi/). @@ -7552,9 +7542 @@ OpenAPI schema version depends on the installed version of Pydantic -Pydantic v1 generates [valid OpenAPI 3.0.3 schemas](https://docs.pydantic.dev/1.10/usage/schema/), and Pydantic v2 generates [valid OpenAPI 3.1.0 schemas](https://docs.pydantic.dev/latest/why/#json-schema). - -In OpenAPI documentation tools like SwaggerUI, these annotations become readable descriptions, offering a self-explanatory API interface. This reduces boilerplate code while improving functionality and enabling auto-documentation. - -Note - -We don't have support for files, form data, and header parameters at the moment. If you're interested in this, please [open an issue](https://github.com/aws-powertools/powertools-lambda-python/issues/new?assignees=&labels=feature-request%2Ctriage&projects=&template=feature_request.yml&title=Feature+request%3A+TITLE). - -#### Customizing OpenAPI parameters¶ +### Custom serializer¶ @@ -7562 +7544 @@ We don't have support for files, form data, and header parameters at the moment. -Whenever you use OpenAPI parameters to validate [query strings](./#validating-query-strings) or [path parameters](./#validating-path-parameters), you can enhance validation and OpenAPI documentation by using any of these parameters: +You can instruct event handler to use a custom serializer to best suit your needs, for example take into account Enums when serializing. @@ -7564,43 +7546 @@ Whenever you use OpenAPI parameters to validate [query strings](./#validating-qu -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/) 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 -`openapi_examples` | `dict[str, Example]` | A list of examples to be displayed in the SwaggerUI interface. Avoid using the `examples` field for this purpose. -`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 - -#### Customizing API operations¶ - -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. -`deprecated` | `bool` | A boolean value that determines whether or not this operation should be marked as deprecated in the OpenAPI schema. - -To implement these customizations, include extra parameters when defining your routes: - -customizing_api_operations.py +Using a custom JSON serializer for responses @@ -7639,0 +7580,28 @@ customizing_api_operations.py + 31 + 32 + 33 + 34 + 35 + 36 + 37 + 38 + 39 + 40 + 41 + 42 + 43 + 44 + 45 + 46 + 47 + 48 + 49 + 50 + 51 + 52 + 53 + 54 + 55 + 56 + 57 + 58 @@ -7643,0 +7612,4 @@ customizing_api_operations.py + import json + from dataclasses import asdict, dataclass, is_dataclass + from json import JSONEncoder + @@ -7644,0 +7617 @@ customizing_api_operations.py + from requests import Response @@ -7645,0 +7619 @@ customizing_api_operations.py + from aws_lambda_powertools import Logger, Tracer @@ -7646,0 +7621 @@ customizing_api_operations.py + from aws_lambda_powertools.logging import correlation_paths @@ -7649 +7624,3 @@ customizing_api_operations.py - app = APIGatewayRestResolver(enable_validation=True) + tracer = Tracer() + logger = Logger() + app = APIGatewayRestResolver() @@ -7652,16 +7629,6 @@ customizing_api_operations.py - @app.get( - "/todos/<todo_id>", - summary="Retrieves a todo item", - description="Loads a todo item identified by the `todo_id`", - response_description="The todo object", - responses={ - 200: {"description": "Todo item found"}, - 404: { - "description": "Item not found", - }, - }, - tags=["Todos"], - ) - def get_todo_title(todo_id: int) -> str: