feat(event_handler): add support for defining OpenAPI examples in parameters

[leandrodamascena]

Issue number: #5587

Summary

Changes

This feature enhances API documentation by introducing a new openapi_examples field for parameters defined in the function, allowing developers to provide concrete examples directly in schema objects.

User experience

from typing import Annotated

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.event_handler.openapi.params import Query
from aws_lambda_powertools.event_handler.openapi.models import Example

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

example1 = Example(summary="Example1", description="Example1", value="b")

@app.get("/todos")
def create_todo(todo: Annotated[int, Query(
            openapi_examples={
                    "first_example": example1,
                }
            )]) -> int:  

    return 1


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]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.26%. Comparing base (df75e42) to head (e4cff52).
Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #6086   +/-   ##
========================================
  Coverage    96.26%   96.26%           
========================================
  Files          234      234           
  Lines        11160    11165    +5     
  Branches       828      830    +2     
========================================
+ Hits         10743    10748    +5     
  Misses         327      327           
  Partials        90       90           

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

[anafalcao]

APPROVED!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud