fix(event-handler): prevent OpenAPI schema bleed when reusing response dictionaries

[oyiz-michael]

Issue number: closes #7711

Summary

Changes

This PR fixes a bug where OpenAPI schema return types were bleeding across routes when reusing response dictionaries. The issue occurred when multiple routes shared the same response dictionary object (e.g., via Responses.combine()), causing the schema generator to mutate the shared dictionary and incorrectly apply one route's return type schema to all routes.

Root cause: The _add_route_to_openapi_routes method was directly referencing the shared response dictionary, so modifications made during schema generation affected all routes using that dictionary.

Solution: Changed line 670 in api_gateway.py to use copy.deepcopy() to create an independent copy of the response dictionary before any modifications, ensuring each route's schema remains isolated.

Files changed:

• aws_lambda_powertools/event_handler/api_gateway.py: Added import copy and modified response dictionary handling to use deepcopy()
• tests/functional/event_handler/_pydantic/test_openapi_shared_response_bleed.py: Added comprehensive regression tests

User experience

Before:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver

responses = Responses.combine(
    Responses.success,
    Responses.not_found
)

@app.get("/exams", responses=responses)
def list_exams() -> list[ExamSummary]:
    ...

@app.get("/exam/<exam_id>/config", responses=responses)
def get_exam_config(exam_id: str) -> ExamConfig:
    ...

The generated OpenAPI schema would incorrectly show both routes returning the same type (whichever was processed last), instead of list[ExamSummary] and ExamConfig respectively.

After:
Each route correctly maintains its own return type schema in the OpenAPI specification, regardless of shared response dictionaries. The /exams route shows list[ExamSummary] and the /exam/<exam_id>/config route shows ExamConfig as expected.

Testing:
Added 2 new regression tests that verify no schema bleed occurs
Code quality checks pass: ruff format, ruff check, mypy
All 323 existing event handler tests pass

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.72%. Comparing base (8761fe7) to head (282d4f4).
⚠️ Report is 1 commits behind head on develop.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #7952   +/-   ##
========================================
  Coverage    96.72%   96.72%           
========================================
  Files          278      278           
  Lines        13626    13627    +1     
  Branches      1083     1083           
========================================
+ Hits         13180    13181    +1     
  Misses         327      327           
  Partials       119      119           

☔ 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
0 New issues
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

[leandrodamascena]

Hey @oyiz-michael thanks a lot for this PR! Approved.