AWS powertools documentation change
Summary
Updated documentation for AWS Lambda Powertools OpenAPI module with significant changes to OpenAPIMerge class, addition of dependent_files property, enhanced discover method with project_root parameter, new schema_generator module, and updates to parameter classes including Dependant, Param, Header, and Form classes.
Security assessment
The changes are focused on improving OpenAPI schema generation functionality, adding support for shared resolver patterns, and enhancing parameter handling. There is no evidence of addressing security vulnerabilities or weaknesses. The warnings added about side effects at import time are related to reliability and functionality, not security. The changes to parameter classes (Param, Header, etc.) are documentation updates for Pydantic integration, not security-related.
Diff
diff --git a/powertools/python/latest/api_doc/event_handler/openapi.md b/powertools/python/latest/api_doc/event_handler/openapi.md index cd8aec452..c4ac6658d 100644 --- a//powertools/python/latest/api_doc/event_handler/openapi.md +++ b//powertools/python/latest/api_doc/event_handler/openapi.md @@ -44,0 +45 @@ Metrics + * [ OpenAPI ](../../../core/event_handler/openapi/) @@ -62,0 +64,5 @@ Metrics + * [ Lambda Features ](../../../lambda-features/) + +Lambda Features + * [ Lambda Managed Instances ](../../../lambda-features/managed-instances/) + * [ Durable Functions ](../../../lambda-features/durable-functions/) @@ -104 +110 @@ Build recipes - * Write to file for API Gateway import or documentation + * dependent_files @@ -138 +144 @@ Build recipes - * Write to file for API Gateway import or documentation + * dependent_files @@ -163,0 +170,2 @@ Build recipes + * schema_generator + * generate_openapi_path @@ -223 +231 @@ Table of contents - * Write to file for API Gateway import or documentation + * dependent_files @@ -257 +265 @@ Table of contents - * Write to file for API Gateway import or documentation + * dependent_files @@ -282,0 +291,2 @@ Table of contents + * schema_generator + * generate_openapi_path @@ -309,0 +320 @@ MODULE | DESCRIPTION +`schema_generator` | OpenAPI schema generation for individual routes. @@ -325,46 +336 @@ Discover and merge OpenAPI schemas from multiple Lambda handlers. -This class is designed for micro-functions architectures where you have multiple Lambda functions, each with its own resolver, and need to generate a unified OpenAPI specification. It's particularly useful for: - - * CI/CD pipelines to generate and publish unified API documentation - * Build-time schema generation for API Gateway imports - * Creating a dedicated Lambda that serves the consolidated OpenAPI spec - - - -The class uses AST analysis to detect resolver instances without importing modules, making discovery fast and safe. - -PARAMETER | DESCRIPTION ----|--- -`title` | The title of the unified API. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `DEFAULT_OPENAPI_TITLE` -`version` | The version of the API (e.g., "1.0.0"). **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `DEFAULT_API_VERSION` -`openapi_version` | The OpenAPI specification version. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `"3.1.0"` -`summary` | A short summary of the API. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `None` -`description` | A detailed description of the API. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `None` -`tags` | Tags for API documentation organization. **TYPE:** `[list](https://docs.python.org/3/library/stdtypes.html#list)[Tag | [str](https://docs.python.org/3/library/stdtypes.html#str)]` **DEFAULT:** `None` -`servers` | Server objects for API connectivity information. **TYPE:** `[list](https://docs.python.org/3/library/stdtypes.html#list)[Server]` **DEFAULT:** `None` -`terms_of_service` | URL to the Terms of Service. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `None` -`contact` | Contact information for the API. **TYPE:** `Contact` **DEFAULT:** `None` -`license_info` | License information for the API. **TYPE:** `License` **DEFAULT:** `None` -`security_schemes` | Security scheme definitions. **TYPE:** `[dict](https://docs.python.org/3/library/stdtypes.html#dict)[[str](https://docs.python.org/3/library/stdtypes.html#str), SecurityScheme]` **DEFAULT:** `None` -`security` | Global security requirements. **TYPE:** `[list](https://docs.python.org/3/library/stdtypes.html#list)[[dict](https://docs.python.org/3/library/stdtypes.html#dict)[[str](https://docs.python.org/3/library/stdtypes.html#str), [list](https://docs.python.org/3/library/stdtypes.html#list)[[str](https://docs.python.org/3/library/stdtypes.html#str)]]]` **DEFAULT:** `None` -`external_documentation` | Link to external documentation. **TYPE:** `ExternalDocumentation` **DEFAULT:** `None` -`openapi_extensions` | OpenAPI specification extensions (x-* fields). **TYPE:** `[dict](https://docs.python.org/3/library/stdtypes.html#dict)[[str](https://docs.python.org/3/library/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any "typing.Any")]` **DEFAULT:** `None` -`on_conflict` | Strategy when the same path+method is defined in multiple handlers: \- "warn": Log warning and keep first definition \- "error": Raise OpenAPIMergeError \- "first": Silently keep first definition \- "last": Use last definition (override) **TYPE:** `[Literal](https://docs.python.org/3/library/typing.html#typing.Literal "typing.Literal")['warn', 'error', 'first', 'last']` **DEFAULT:** `"warn"` -Example - -**CI/CD Pipeline - Generate unified schema at build time:** - -> > > from aws_lambda_powertools.event_handler.openapi import OpenAPIMerge ->>> ->>> merge = OpenAPIMerge( ... title="My Unified API", ... version="1.0.0", ... description="Consolidated API from multiple Lambda functions", ... ) merge.discover( ... path="./src/functions", ... pattern="**/handler.py", ... exclude=["** /tests/**"], ... ) schema_json = merge.get_openapi_json_schema() ->>> ->>> ### Write to file for API Gateway import or documentation¶ ->>> ->>> with open("openapi.json", "w") as f: ... f.write(schema_json) - -**Dedicated OpenAPI Lambda - Serve unified spec at runtime:** - -> > > from aws_lambda_powertools.event_handler import APIGatewayRestResolver ->>> ->>> app = APIGatewayRestResolver() app.configure_openapi_merge( ... path="./functions", ... pattern="**/handler.py", ... title="My API", ... version="1.0.0", ... ) app.enable_swagger(path="/docs") # Swagger UI with merged schema ->>> ->>> def handler(event, context): ... return app.resolve(event, context) +This class supports two patterns: 1\. Standard pattern: Each handler file defines its own resolver with routes 2\. Shared resolver pattern: A central resolver file is imported by multiple handler files that register routes on it @@ -372,3 +338 @@ Example -See Also - -OpenAPIMergeError : Exception raised on merge conflicts when on_conflict="error" +For the shared resolver pattern, this class automatically discovers files that import the resolver and loads them before extracting the schema, ensuring all routes are registered. @@ -380,3 +344,3 @@ METHOD | DESCRIPTION -`discover` | Discover resolver files in the specified path using glob patterns. -`get_openapi_json_schema` | Generate the merged OpenAPI schema as a JSON string. -`get_openapi_schema` | Generate the merged OpenAPI schema as a dictionary. +`discover` | Discover resolver files and their dependent handler files. +`get_openapi_json_schema` | Generate the merged OpenAPI schema as JSON string. +`get_openapi_schema` | Generate the merged OpenAPI schema. @@ -384,0 +349 @@ ATTRIBUTE | DESCRIPTION +`dependent_files` | Get the mapping of resolver files to their dependent handler files. **TYPE:** `[dict](https://docs.python.org/3/library/stdtypes.html#dict)[[Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "pathlib.Path"), [list](https://docs.python.org/3/library/stdtypes.html#list)[[Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "pathlib.Path")]]` @@ -389,13 +353,0 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` - 270 - 271 - 272 - 273 - 274 - 275 - 276 - 277 - 278 - 279 - 280 - 281 - 282 @@ -428,0 +381,16 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` + 310 + 311 + 312 + 313 + 314 + 315 + 316 + 317 + 318 + 319 + 320 + 321 + 322 + 323 + 324 + 325 @@ -469,0 +438 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` + self._dependent_files: dict[Path, list[Path]] = {} @@ -472,0 +442,2 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` + self._root: Path | None = None + self._exclude: list[str] = [] @@ -476,0 +448,8 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` +### dependent_files `property` ¶ + + + dependent_files: dict[Path, list[Path]] + + +Get the mapping of resolver files to their dependent handler files. + @@ -498,11 +477,11 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` - 359 - 360 - 361 - 362 - 363 - 364 - 365 - 366 - 367 - 368 - 369 + 371 + 372 + 373 + 374 + 375 + 376 + 377 + 378 + 379 + 380 + 381 @@ -541,7 +520,7 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` - 371 - 372 - 373 - 374 - 375 - 376 - 377 + 383 + 384 + 385 + 386 + 387 + 388 + 389 @@ -566,2 +545 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` - discover(path: str | Path, pattern: str | list[str] = 'handler.py', exclude: list[str] | None = None, resolver_name: str = 'app', recursive: bool = False) -> list[Path] - + discover(path: str | Path, pattern: str | list[str] = 'handler.py', exclude: list[str] | None = None, resolver_name: str = 'app', recursive: bool = False, project_root: str | Path | None = None) -> list[Path] @@ -569 +546,0 @@ Source code in `aws_lambda_powertools/event_handler/openapi/merge.py` -Discover resolver files in the specified path using glob patterns. @@ -571 +548 @@ Discover resolver files in the specified path using glob patterns. -This method scans the directory tree for Python files matching the pattern, then uses AST analysis to identify files containing resolver instances. +Discover resolver files and their dependent handler files. @@ -575,12 +552,6 @@ PARAMETER | DESCRIPTION -`path` | Root directory to search for handler files. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str) | [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "pathlib.Path")` -`pattern` | Glob pattern(s) to match handler files. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str) | [list](https://docs.python.org/3/library/stdtypes.html#list)[[str](https://docs.python.org/3/library/stdtypes.html#str)]` **DEFAULT:** `"handler.py"` -`exclude` | Patterns to exclude. Defaults to ["**/tests/** ", "**/**pycache** /**", "**/.venv/** "]. **TYPE:** `[list](https://docs.python.org/3/library/stdtypes.html#list)[[str](https://docs.python.org/3/library/stdtypes.html#str)]` **DEFAULT:** `None` -`resolver_name` | Variable name of the resolver instance in handler files. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str)` **DEFAULT:** `"app"` -`recursive` | Whether to search recursively in subdirectories. **TYPE:** `[bool](https://docs.python.org/3/library/functions.html#bool)` **DEFAULT:** `False` -RETURNS | DESCRIPTION ----|--- -`[list](https://docs.python.org/3/library/stdtypes.html#list)[[Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "pathlib.Path")]` | List of discovered files containing resolver instances. -Example - -> > > merge = OpenAPIMerge(title="API", version="1.0.0") files = merge.discover( ... path="./src", ... pattern=["handler.py", "api.py"], ... exclude=["**/tests/** ", "**/legacy/** "], ... recursive=True, ... ) print(f"Found {len(files)} handlers") - +`path` | Directory to search for resolver files. **TYPE:** `[str](https://docs.python.org/3/library/stdtypes.html#str) | [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path "pathlib.Path")`