AWS powertools documentation change

Service: powertools · 2025-10-10 · Documentation low

File: powertools/python/latest/api_doc/event_handler/openapi.md

Summary

Added documentation for OpenAPIResponseHeader type and updated parameter handling logic for field annotations

Security assessment

Changes primarily add documentation for a new response header type and modify annotation validation logic. While parameter handling changes could relate to input validation security, there's no explicit mention of vulnerability fixes or security improvements in the diff. The OpenAPIResponseHeader documentation doesn't specifically describe security-related headers.

Diff

diff --git a/powertools/python/latest/api_doc/event_handler/openapi.md b/powertools/python/latest/api_doc/event_handler/openapi.md
index eb5f3d3b9..c56410322 100644
--- a//powertools/python/latest/api_doc/event_handler/openapi.md
+++ b//powertools/python/latest/api_doc/event_handler/openapi.md
@@ -147,0 +148,2 @@ Build recipes
+        * types 
+          * OpenAPIResponseHeader 
@@ -241,0 +244,2 @@ Table of contents
+  * types 
+    * OpenAPIResponseHeader 
@@ -255,0 +260 @@ MODULE | DESCRIPTION
+`types` |   
@@ -3466,22 +3471,22 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-    1073
-    1074
-    1075
-    1076
-    1077
-    1078
-    1079
-    1080
-    1081
-    1082
-    1083
-    1084
-    1085
-    1086
-    1087
-    1088
-    1089
-    1090
-    1091
-    1092
-    1093
-    1094
+    1139
+    1140
+    1141
+    1142
+    1143
+    1144
+    1145
+    1146
+    1147
+    1148
+    1149
+    1150
+    1151
+    1152
+    1153
+    1154
+    1155
+    1156
+    1157
+    1158
+    1159
+    1160
@@ -3604,31 +3609,33 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-    1040
-    1041
-    1042
-    1043
-    1044
-    1045
-    1046
-    1047
-    1048
-    1049
-    1050
-    1051
-    1052
-    1053
-    1054
-    1055
-    1056
-    1057
-    1058
-    1059
-    1060
-    1061
-    1062
-    1063
-    1064
-    1065
-    1066
-    1067
-    1068
-    1069
-    1070
+    1104
+    1105
+    1106
+    1107
+    1108
+    1109
+    1110
+    1111
+    1112
+    1113
+    1114
+    1115
+    1116
+    1117
+    1118
+    1119
+    1120
+    1121
+    1122
+    1123
+    1124
+    1125
+    1126
+    1127
+    1128
+    1129
+    1130
+    1131
+    1132
+    1133
+    1134
+    1135
+    1136
@@ -3643 +3649,0 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-        field_info: FieldInfo | None = None
@@ -3648,2 +3654,3 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-        if len(powertools_annotations) > 1:
-            raise AssertionError("Only one FieldInfo can be used per parameter")
+        # Determine which annotation to use
+        powertools_annotation: FieldInfo | None = None
+        has_discriminator_with_param = False
@@ -3650,0 +3658,8 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
+        if len(powertools_annotations) == 2:
+            powertools_annotation, type_annotation, has_discriminator_with_param = _handle_discriminator_with_param(
+                powertools_annotations,
+                annotation,
+            )
+        elif len(powertools_annotations) > 1:
+            raise AssertionError("Only one FieldInfo can be used per parameter")
+        else:
@@ -3653,8 +3668,5 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-        if isinstance(powertools_annotation, FieldInfo):
-            # Copy `field_info` because we mutate `field_info.default` later
-            field_info = copy_field_info(
-                field_info=powertools_annotation,
-                annotation=annotation,
-            )
-            if field_info.default not in [Undefined, Required]:
-                raise AssertionError("FieldInfo needs to have a default value of Undefined or Required")
+        # Process the annotation if it exists
+        field_info: FieldInfo | None = None
+        if isinstance(powertools_annotation, FieldInfo):  # pragma: no cover
+            field_info = _create_field_info(powertools_annotation, type_annotation, has_discriminator_with_param)
+            _set_field_default(field_info, value, is_path_param)
@@ -3662,6 +3674,3 @@ Source code in `aws_lambda_powertools/event_handler/openapi/params.py`
-            if value is not inspect.Signature.empty:
-                if is_path_param:
-                    raise AssertionError("Cannot use a FieldInfo as a path parameter and pass a value")
-                field_info.default = value
-            else:
-                field_info.default = Required
+            # Preserve full annotated type for discriminated unions
+            if _has_discriminator(powertools_annotation):  # pragma: no cover
+                type_annotation = annotation  # pragma: no cover
@@ -4628,0 +4638,12 @@ Source code in `aws_lambda_powertools/event_handler/openapi/swagger_ui/oauth2.py
+##  types ¶
+
+CLASS | DESCRIPTION  
+---|---  
+`OpenAPIResponseHeader` |  OpenAPI Response Header Object  
+  
+###  OpenAPIResponseHeader ¶
+
+Bases: `[TypedDict](https://docs.python.org/3/library/typing.html#typing.TypedDict "typing.TypedDict")`
+
+OpenAPI Response Header Object
+