[SpinachDigital]

Closes #8583.

Six fixes, all in the OpenAPI lane:

1. Custom responses without content no longer inherit the handler's return schema for every status code — only the route's own status code gets the return-type content; a description-only 404 stays description-only (_build_custom_response).

2. Pydantic-model Query()/Header() fields now build schemas with TypeAdapter(annotation).json_schema() — int | None renders as anyOf, list[str] as array, Enums with their values, instead of everything collapsing to {"type": "string"}.

3. ValidationError component no longer lists msg in required — it is not in properties (hidden for security) nor in the real 422 body.

4. openapi_extensions now enforces the x- prefix at the root (get_openapi) and at the operation level, raising the same SchemaValidationError that Server and SecurityScheme already raise.

5. Path(alias=...): validation looks path params up by the template name again (was a 422 missing), and the emitted parameter name matches the path template.

6. decimal_encoder raises SerializationError for non-finite Decimals (NaN/Infinity) instead of leaking TypeError: '>=' not supported between 'str' and 'int'.

Also updates two assertions in test_openapi_params.py that pinned the old {"type": "string"} rendering for str | None fields.

Verified locally before opening: the issue's repro snippet now passes for all 6 items, and the repo's openapi functional suites pass (including the two updated assertions).

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[boring-cyborg]

Thanks a lot for your first contribution! Please check out our contributing guidelines and don't hesitate to ask whatever you need.
In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link

[leandrodamascena]

Thanks @SpinachDigital, all six are fixed and I checked each one against develop side by side, including a richer Query model with datetime, UUID and Literal fields, which now come out with the right format and enum.

One thing would have failed CI: the loop you added to get_openapi_schema pushes it over our ruff complexity limits (C901, PLR0912). You had already written _validate_openapi_extension_keys in the schema generator, so I pushed a small commit that calls it from there instead. Nothing else changed.

Approving. This goes out in 3.39.0, so it will sit here for a while before I merge it. No rebase needed in the meantime, and you'll be credited in the release notes. I'll flag the x- enforcement and the custom-responses change in the notes since both are visible to people who relied on the old behavior.

[codecov]

Codecov Report

❌ Patch coverage is 70.58824% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 96.90%. Comparing base (0f64f28) to head (19b7fab).
⚠️ Report is 24 commits behind head on develop.

Files with missing lines	Patch %	Lines
...wertools/event_handler/openapi/schema_generator.py	76.92%	2 Missing and 1 partial ⚠️
...ambda_powertools/event_handler/openapi/encoders.py	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8630      +/-   ##
===========================================
- Coverage    96.93%   96.90%   -0.04%     
===========================================
  Files          318      321       +3     
  Lines        16031    16257     +226     
  Branches      1423     1456      +33     
===========================================
+ Hits         15540    15754     +214     
- Misses         349      358       +9     
- Partials       142      145       +3     

☔ View full report in Codecov by Harness.
📢 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.

[leandrodamascena]

Follow-up push: the PR fixed six behaviors but only adjusted two existing assertions, so four of the new lines had no test. I added regression tests for each item through the public API, description-only custom responses, Query model field types plus the string fallback, ValidationError.required, the x- check at root and operation level, Path(alias=...) and non-finite Decimal. Patch coverage is 100% now. Approval stands.

[leandrodamascena]

Re-approving after the test push above.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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