feat(event_handler): add support for form data in OpenAPI utility

aws_lambda_powertools/event_handler/openapi/dependant.py

@@ -348,6 +348,7 @@ def get_body_field(*, dependant: Dependant, name: str) -> ModelField | None:
         alias="body",
         field_info=body_field_info(**body_field_info_kwargs),
     )
+
     return final_field
 
 
@@ -367,11 +368,11 @@ def get_body_field_info(
         body_field_info_kwargs["default"] = None
 
     if any(isinstance(f.field_info, _File) for f in flat_dependant.body_params):
-        # MAINTENANCE: body_field_info: type[Body] = _File
-        raise NotImplementedError("_File fields are not supported in request bodies")
+        body_field_info = Body
+        body_field_info_kwargs["media_type"] = "multipart/form-data"
     elif any(isinstance(f.field_info, _Form) for f in flat_dependant.body_params):
-        # MAINTENANCE: body_field_info: type[Body] = _Form
-        raise NotImplementedError("_Form fields are not supported in request bodies")
+        body_field_info = Body
+        body_field_info_kwargs["media_type"] = "application/x-www-form-urlencoded"
     else:
         body_field_info = Body
 

aws_lambda_powertools/event_handler/openapi/models.py

@@ -481,6 +481,8 @@ class OpenAPI(OpenAPIExtensions):
     model_config = MODEL_CONFIG_ALLOW
 
 
+
+
 model_rebuild(Schema)
 model_rebuild(Operation)
 model_rebuild(Encoding)

aws_lambda_powertools/event_handler/openapi/params.py

@@ -848,6 +848,13 @@ def __init__(
         json_schema_extra: dict[str, Any] | None = None,
         **extra: Any,
     ):
+        # For file uploads, ensure the OpenAPI schema has the correct format
+        file_schema_extra = {"format": "binary"}
+        if json_schema_extra:
+            json_schema_extra.update(file_schema_extra)
+        else:
+            json_schema_extra = file_schema_extra
+
         super().__init__(
             default=default,
             default_factory=default_factory,
@@ -1122,3 +1129,9 @@ def _create_model_field(
         required=field_info.default in (Required, Undefined),
         field_info=field_info,
     )
+
+
+# Public type aliases for form and file parameters
+# Use Annotated types to work properly with Pydantic
+File = Annotated[bytes, _File()]
+Form = Annotated[str, _Form()]

docs/core/event_handler/api_gateway.md

@@ -523,6 +523,81 @@ In the following example, we use a new `Header` OpenAPI type to add [one out of
 
     1. `cloudfront_viewer_country` is a list that must contain values from the `CountriesAllowed` enumeration.
 
+#### Handling file uploads and form data
+
+!!! info "You must set `enable_validation=True` to handle file uploads and form data via type annotation."
+
+We use the `Annotated` type to tell the Event Handler that a parameter expects file upload or form data. This automatically sets the correct OpenAPI schema for `multipart/form-data` requests.
+
+In the following example, we use `File` and `Form` OpenAPI types to handle file uploads and form fields:
+
+* `File` parameters expect binary file data and generate OpenAPI schema with `format: binary`
+* `Form` parameters expect form field values from multipart form data
+* The OpenAPI spec will automatically set `requestBody` content type to `multipart/form-data`
+
+=== "handling_file_uploads.py"
+
+    ```python hl_lines="5 9-10 18-19"
+    from typing import Annotated
+    from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+    from aws_lambda_powertools.event_handler.openapi.params import File, Form
+
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/upload")
+    def upload_file(
+        file: Annotated[bytes, File(description="File to upload")],
+        filename: Annotated[str, Form(description="Name of the file")]
+    ):
+        # file contains the binary data of the uploaded file
+        # filename contains the form field value
+        return {
+            "message": f"Uploaded {filename}",
+            "size": len(file)
+        }
+
+    def lambda_handler(event, context):
+        return app.resolve(event, context)
+    ```
+
+    1. If you're not using Python 3.9 or higher, you can install and use [`typing_extensions`](https://pypi.org/project/typing-extensions/){target="_blank" rel="nofollow"} to the same effect
+    2. `File` is a special OpenAPI type for binary file uploads that sets `format: binary` in the schema
+    3. `Form` is a special OpenAPI type for form field values in multipart requests
+
+=== "Multiple files"
+
+    You can handle multiple file uploads by declaring parameters as lists:
+
+    ```python hl_lines="9-10"
+    from typing import Annotated, List
+    from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+    from aws_lambda_powertools.event_handler.openapi.params import File, Form
+
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/upload-multiple")
+    def upload_multiple_files(
+        files: Annotated[List[bytes], File(description="Files to upload")],
+        description: Annotated[str, Form(description="Upload description")]
+    ):
+        return {
+            "message": f"Uploaded {len(files)} files",
+            "description": description,
+            "total_size": sum(len(file) for file in files)
+        }
+    ```
+
+    1. `files` will be a list containing the binary data of each uploaded file
+
+???+ note "OpenAPI Schema Generation"
+    When you use `File` or `Form` parameters, the generated OpenAPI specification will automatically include:
+
+    * `requestBody` with content type `multipart/form-data`
+    * Proper schema definitions with `format: binary` for file parameters
+    * Form field descriptions and constraints
+
+    This ensures API documentation tools like SwaggerUI correctly display file upload interfaces.
+
 #### Supported types for response serialization
 
 With data validation enabled, we natively support serializing the following data types to JSON: