[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

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.97%. Comparing base (7ce6851) to head (96dd320).

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #8630   +/-   ##
========================================
  Coverage    96.97%   96.97%           
========================================
  Files          321      321           
  Lines        16288    16300   +12     
  Branches      1462     1465    +3     
========================================
+ Hits         15795    15807   +12     
  Misses         352      352           
  Partials       141      141           

☔ 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
3 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]

Thanks @SpinachDigital, pushed two small things on top of your branch. develop moved and the test file conflicted with #8602, so I merged it in and kept both sets of tests. I also changed the x- check to a warning instead of an exception. I kept thinking about an app that already serves /swagger with a wrongly prefixed extension: with the exception, that endpoint would start failing the moment they upgrade, and I'd rather they see a warning and fix it on their own time. It becomes an error in the next major. The two tests now check the warning and that the extension is still emitted. Nothing else in your work changed. Re-approving and merging when CI is green.

[boring-cyborg]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!

[powertools-for-aws-oss-automation]

Awesome work, congrats on your first merged pull request and thank you for helping improve everyone's experience!