feat(event_handler): support Header parameter validation in OpenAPI schema

[leandrodamascena]

Issue number: #3661

Summary

Changes

This pull request aims to enhance the OpenAPI schema by allowing the definition of headers as part of API specifications. An API call may require that custom headers be sent with an HTTP request. OpenAPI lets you define custom request headers as in: header parameters.

Key Changes:

• Added support for defining custom headers within the OpenAPI schema.
• Updated the OpenAPI documentation to showcase the usage of custom header parameters.
• Refactored the tests to reduce the number of the code

User experience

from typing import List

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import Header
from aws_lambda_powertools.shared.types import Annotated  
from aws_lambda_powertools.utilities.typing import LambdaContext

app = APIGatewayRestResolver(enable_validation=True)

@app.get("/hello")
def get_hello(header2: Annotated[List[str], Header()], header1: Annotated[str, Header()]):
    print(header2)

def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

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-commenter]

Codecov Report

Attention: 5 lines in your changes are missing coverage. Please review.

Comparison is base (ced0a3d) 95.53% compared to head (5917ddf) 95.58%.

Files	Patch %	Lines
...ls/event_handler/middlewares/openapi_validation.py	90.00%	2 Missing ⚠️
.../utilities/data_classes/api_gateway_proxy_event.py	84.61%	1 Missing and 1 partial ⚠️
...lambda_powertools/utilities/data_classes/common.py	66.66%	1 Missing ⚠️

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #3687      +/-   ##
===========================================
+ Coverage    95.53%   95.58%   +0.04%     
===========================================
  Files          215      215              
  Lines        10088    10136      +48     
  Branches       862     1865    +1003     
===========================================
+ Hits          9638     9688      +50     
+ Misses         340      339       -1     
+ Partials       110      109       -1     

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

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[leandrodamascena]

@rubenfonseca this PR is ready to review. I want to highlight one point that you may want to change/refactor.

According to the RFC, headers are case insensitive, so I lower the header names when resolving them in the DataClass and lower the parameter name as well when validating the OpenAPI schema. Even this is against Python standards, but a customer can create a function like this:

@app.get("/hello")
def get(
    HeADer1: Annotated[
        str,
        Header(
            description="This is multi value header parameter.",
        ),
    ],
):
    """Return validated multi-value header values."""
    return HeADer1

We must be able to compare "HeADer1" with the header name "header1" or "Heder1" or "HEader1".

Thanks

[github-actions]

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

[rubenfonseca]

This is great work, I only need to check the documentation now.
As we spoke during peer review, try to see if we can move the .lower inside the Header's class alias setter. This way we can remove some if/elses in the code and streamline the feature.
Great work Leandro!

[rubenfonseca]

Great job with the code, much cleaner! Just left some final comments on the documentation.

[sonarcloud]

Quality Gate passed

Kudos, no new issues were introduced!

0 New issues
0 Security Hotspots
No data about Coverage
No data about Duplication

See analysis details on SonarCloud