Feature request: Add File parameter support for OpenAPI multipart/form-data file uploads

[oyiz-michael]

Use case

As a developer building serverless APIs with AWS Lambda Powertools, I need to handle file uploads (images, documents, PDFs, etc.) through my API endpoints with proper validation and OpenAPI documentation.

Currently, I can only handle JSON payloads and form data (application/x-www-form-urlencoded) but cannot process multipart/form-data file uploads. This forces me to:

1. Manually parse multipart data - Complex, error-prone, and doesn't integrate with OpenAPI validation
2. Use workarounds like base64-encoded JSON payloads - Inefficient and not standard
3. Skip validation - Missing out on Powertools' automatic validation benefits
4. Write custom OpenAPI schemas - Manual work that should be automated

Common scenarios I need to support:

• Profile image uploads - Users uploading avatar images
• Document processing - PDF uploads for analysis or conversion
• Batch file imports - CSV/Excel file uploads for data processing
• Multiple file uploads - Image galleries, document collections
• Mixed form data - File uploads with metadata (title, description, tags)

This is a standard web development requirement that other frameworks like FastAPI, Django, and Express.js handle seamlessly.

Solution/User Experience

Add a File parameter type that works seamlessly with the existing OpenAPI validation system, providing the same developer experience as Query, Header, and Form parameters.

Proposed Developer Experience:

Simple File Upload

from typing_extensions import Annotated
from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import File

app = APIGatewayRestResolver(enable_validation=True)

@app.post("/upload")
def upload_file(file: Annotated[bytes, File(description="File to upload")]):
    return {"file_size": len(file)}


**File Upload with Validation**

@app.post("/upload-image")
def upload_image(
    file: Annotated[bytes, File(
        description="Image file (max 5MB)",
        min_length=1024,      # Minimum 1KB
        max_length=5242880,   # Maximum 5MB
    )]
):
    return {"message": "Image uploaded successfully"}

**Multiple Files + Metadata**

from aws_lambda_powertools.event_handler.openapi.params import File, Form

@app.post("/gallery-upload")
def upload_gallery(
    image1: Annotated[bytes, File(description="First image")],
    image2: Annotated[bytes, File(description="Second image")],
    title: Annotated[str, Form(description="Gallery title")],
    description: Annotated[str, Form(description="Gallery description")]
):
    return {
        "gallery_title": title,
        "images_uploaded": 2,
        "total_size": len(image1) + len(image2)
    }

### Alternative solutions

```markdown

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET

[leandrodamascena]

Hey @oyiz-michael! Nice to see you again! I'm assigning this to you! Feel free to submit a PR and I can review.