feat(event_handler): add File parameter support for multipart/form-data uploads

[leandrodamascena]

Issue number: closes #7124

This PR is a continuation of the work from PR #7132 opened by @oyiz-michael.

Summary

Customers can now handle file uploads in your API endpoints with full OpenAPI validation and Swagger UI support - just like you'd do with Query(), Header(), or Form().

Changes

Please provide a summary of what's being changed

User experience

Simple file upload

from typing import Annotated
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import File, UploadFile

app = APIGatewayRestResolver(enable_validation=True)
app.enable_swagger(path="/swagger")

@app.post("/upload")
def upload(file_data: Annotated[UploadFile, File(description="File to upload")]):
    return {
        "filename": file_data.filename,
        "content_type": file_data.content_type,
        "file_size": len(file_data),
    }

File upload with form fields

@app.post("/upload-csv")
def upload_csv(
    file_data: Annotated[UploadFile, File(description="CSV file")],
    separator: Annotated[str, Form(description="CSV separator")] = ",",
):
    text = file_data.content.decode("utf-8")
    ...

Two ways to receive files

Annotation	What you get
Annotated[bytes, File()]	Raw file content
Annotated[UploadFile, File()]	File content + filename + content_type

Swagger UI

Swagger renders a file picker for every File() parameter - no extra configuration needed.

API Gateway REST API (v1)

If using REST API v1, you must configure Binary Media Types in your SAM/CloudFormation template:

Globals:
  Api:
    BinaryMediaTypes:
      - "multipart~1form-data"

API Gateway HTTP API (v2), Lambda Function URL, and ALB work out of the box.

A warnings.warn() is emitted at runtime if a multipart request arrives without base64 encoding, helping developers catch missing configuration early.

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[codecov]

Codecov Report

❌ Patch coverage is 95.49550% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.62%. Comparing base (7323c05) to head (b104888).

Files with missing lines	Patch %	Lines
...ls/event_handler/middlewares/openapi_validation.py	94.25%	1 Missing and 4 partials ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8093      +/-   ##
===========================================
- Coverage    96.63%   96.62%   -0.01%     
===========================================
  Files          283      283              
  Lines        13862    13969     +107     
  Branches      1111     1136      +25     
===========================================
+ Hits         13395    13498     +103     
  Misses         342      342              
- Partials       125      129       +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud