add comprehensive tests for File/Form OpenAPI support

Author: oyiz-michael

docs/core/event_handler/api_gateway.md

@@ -538,26 +538,7 @@ In the following example, we use `File` and `Form` OpenAPI types to handle file
 === "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)
+    --8<-- "examples/event_handler_rest/src/handling_file_uploads.py"
     ```
 
     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
@@ -569,22 +550,7 @@ In the following example, we use `File` and `Form` OpenAPI types to handle file
     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)
-        }
+    --8<-- "examples/event_handler_rest/src/handling_multiple_file_uploads.py"
     ```
 
     1. `files` will be a list containing the binary data of each uploaded file

examples/event_handler_rest/src/handling_file_uploads.py

@@ -0,0 +1,23 @@
+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)

examples/event_handler_rest/src/handling_multiple_file_uploads.py

@@ -0,0 +1,22 @@
+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)
+    }
+
+
+def lambda_handler(event, context):
+    return app.resolve(event, context)

tests/functional/event_handler/_pydantic/test_openapi_params.py

@@ -649,3 +649,271 @@ def handler(
     assert parameter.schema_.type == "integer"
     assert parameter.schema_.default == 1
     assert parameter.schema_.title == "Count"
+
+
+def test_openapi_file_upload_parameters():
+    """Test File parameter generates correct OpenAPI schema for file uploads."""
+    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")]
+    ):
+        return {"message": f"Uploaded {filename}", "size": len(file)}
+
+    schema = app.get_openapi_schema()
+    
+    # Check that the endpoint is present
+    assert "/upload" in schema.paths
+    
+    post_op = schema.paths["/upload"].post
+    assert post_op is not None
+    
+    # Check request body
+    request_body = post_op.requestBody
+    assert request_body is not None
+    assert request_body.required is True
+    
+    # Check content type is multipart/form-data
+    assert "multipart/form-data" in request_body.content
+    
+    # Get the schema reference
+    multipart_content = request_body.content["multipart/form-data"]
+    assert multipart_content.schema_ is not None
+    
+    # Check that it references a component schema
+    schema_ref = multipart_content.schema_.ref
+    assert schema_ref is not None
+    assert schema_ref.startswith("#/components/schemas/")
+    
+    # Get the component schema name
+    component_name = schema_ref.split("/")[-1]
+    assert component_name in schema.components.schemas
+    
+    # Check the component schema properties
+    component_schema = schema.components.schemas[component_name]
+    properties = component_schema.properties
+    
+    # Check file parameter
+    assert "file" in properties
+    file_prop = properties["file"]
+    assert file_prop.type == "string"
+    assert file_prop.format == "binary"  # This is the key assertion
+    assert file_prop.title == "File"
+    assert file_prop.description == "File to upload"
+    
+    # Check form parameter
+    assert "filename" in properties
+    filename_prop = properties["filename"]
+    assert filename_prop.type == "string"
+    assert filename_prop.title == "Filename"
+    assert filename_prop.description == "Name of the file"
+    
+    # Check required fields
+    assert component_schema.required == ["file", "filename"]
+
+
+def test_openapi_form_only_parameters():
+    """Test Form parameters generate application/x-www-form-urlencoded content type."""
+    from aws_lambda_powertools.event_handler.openapi.params import _Form
+    
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/form-data")
+    def create_form_data(
+        name: Annotated[str, _Form(description="User name")],
+        email: Annotated[str, _Form(description="User email")] = "[email protected]"
+    ):
+        return {"name": name, "email": email}
+
+    schema = app.get_openapi_schema()
+    
+    # Check that the endpoint is present
+    assert "/form-data" in schema.paths
+    
+    post_op = schema.paths["/form-data"].post
+    assert post_op is not None
+    
+    # Check request body
+    request_body = post_op.requestBody
+    assert request_body is not None
+    
+    # Check content type is application/x-www-form-urlencoded
+    assert "application/x-www-form-urlencoded" in request_body.content
+    
+    # Get the schema reference
+    form_content = request_body.content["application/x-www-form-urlencoded"]
+    assert form_content.schema_ is not None
+    
+    # Check that it references a component schema
+    schema_ref = form_content.schema_.ref
+    assert schema_ref is not None
+    assert schema_ref.startswith("#/components/schemas/")
+    
+    # Get the component schema
+    component_name = schema_ref.split("/")[-1]
+    assert component_name in schema.components.schemas
+    
+    component_schema = schema.components.schemas[component_name]
+    properties = component_schema.properties
+    
+    # Check form parameters
+    assert "name" in properties
+    name_prop = properties["name"]
+    assert name_prop.type == "string"
+    assert name_prop.description == "User name"
+    
+    assert "email" in properties
+    email_prop = properties["email"]
+    assert email_prop.type == "string"
+    assert email_prop.description == "User email"
+    assert email_prop.default == "[email protected]"
+    
+    # Check required fields (only name should be required since email has default)
+    assert component_schema.required == ["name"]
+
+
+def test_openapi_mixed_file_and_form_parameters():
+    """Test mixed File and Form parameters use multipart/form-data."""
+    from aws_lambda_powertools.event_handler.openapi.params import _File, _Form
+    
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/mixed")
+    def upload_with_metadata(
+        file: Annotated[bytes, _File(description="Document to upload")],
+        title: Annotated[str, _Form(description="Document title")],
+        category: Annotated[str, _Form(description="Document category")] = "general"
+    ):
+        return {
+            "title": title,
+            "category": category,
+            "file_size": len(file)
+        }
+
+    schema = app.get_openapi_schema()
+    
+    # Check that the endpoint is present
+    assert "/mixed" in schema.paths
+    
+    post_op = schema.paths["/mixed"].post
+    request_body = post_op.requestBody
+    
+    # When both File and Form parameters are present, should use multipart/form-data
+    assert "multipart/form-data" in request_body.content
+    
+    # Get the component schema
+    multipart_content = request_body.content["multipart/form-data"]
+    schema_ref = multipart_content.schema_.ref
+    component_name = schema_ref.split("/")[-1]
+    component_schema = schema.components.schemas[component_name]
+    
+    properties = component_schema.properties
+    
+    # Check file parameter has binary format
+    assert "file" in properties
+    file_prop = properties["file"]
+    assert file_prop.format == "binary"
+    
+    # Check form parameters are present
+    assert "title" in properties
+    assert "category" in properties
+    
+    # Check required fields
+    assert "file" in component_schema.required
+    assert "title" in component_schema.required
+    assert "category" not in component_schema.required  # has default value
+
+
+def test_openapi_multiple_file_uploads():
+    """Test multiple file uploads with List[bytes] type."""
+    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)
+        }
+
+    schema = app.get_openapi_schema()
+    
+    # Check that the endpoint is present
+    assert "/upload-multiple" in schema.paths
+    
+    post_op = schema.paths["/upload-multiple"].post
+    request_body = post_op.requestBody
+    
+    # Should use multipart/form-data for file uploads
+    assert "multipart/form-data" in request_body.content
+    
+    # Get the component schema
+    multipart_content = request_body.content["multipart/form-data"]
+    schema_ref = multipart_content.schema_.ref
+    component_name = schema_ref.split("/")[-1]
+    component_schema = schema.components.schemas[component_name]
+    
+    properties = component_schema.properties
+    
+    # Check files parameter
+    assert "files" in properties
+    files_prop = properties["files"]
+    
+    # For List[bytes] with File annotation, should be array of strings with binary format
+    assert files_prop.type == "array"
+    assert files_prop.items.type == "string"
+    assert files_prop.items.format == "binary"
+    
+    # Check form parameter
+    assert "description" in properties
+    description_prop = properties["description"]
+    assert description_prop.type == "string"
+
+
+def test_openapi_public_file_form_exports():
+    """Test that File and Form are properly exported for public use."""
+    from aws_lambda_powertools.event_handler.openapi.params import File, Form
+    
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    @app.post("/public-api")
+    def upload_with_public_types(
+        file: File,  # Using the public export
+        name: Form   # Using the public export
+    ):
+        return {"status": "uploaded"}
+
+    schema = app.get_openapi_schema()
+    
+    # Check that the endpoint works with public exports
+    assert "/public-api" in schema.paths
+    
+    post_op = schema.paths["/public-api"].post
+    request_body = post_op.requestBody
+    
+    # Should generate multipart/form-data
+    assert "multipart/form-data" in request_body.content
+    
+    # Get the component schema
+    multipart_content = request_body.content["multipart/form-data"]
+    schema_ref = multipart_content.schema_.ref
+    component_name = schema_ref.split("/")[-1]
+    component_schema = schema.components.schemas[component_name]
+    
+    properties = component_schema.properties
+    
+    # Check that both parameters are present and correctly typed
+    assert "file" in properties
+    assert properties["file"].format == "binary"
+    
+    assert "name" in properties
+    assert properties["name"].type == "string"