feat(openapi): add multipart/form-data & form support- documentation

Author: oyiz-michael

aws_lambda_powertools/event_handler/openapi/params.py

@@ -1132,5 +1132,6 @@ def _create_model_field(
 
 
 # Public type aliases for form and file parameters
-File = _File
-Form = _Form
+# 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: