fix(event_handler): OpenAPI schema version respects Pydantic version

[rubenfonseca]

Issue number: #3731

Summary

Changes

Please provide a summary of what's being changed

This PR forces the OpenAPI schema version to follow the Pydantic version. Pydantic v1 only generates OpenAPI Schema 3.0.x, and Pydantic v2 only generates OpenAPI Schema 3.1.x.

List of tasks in this PR:

• Determines the default OpenAPI schema version according to the installed Pydantic version
• Emits a warning if the user requests an OpenAPI schema version that is incompatible with the current installed Pydantic version
• Adapts the schema to version 3.0.x and 3.1.x, removing things that are unnecessary
• Add automated tests for both pydantic v1 and v2 that generate simple and complex schemas, and validate them against the official OpenAPI spec (using fastjsonschema)
• Refactored the pytest fixtures to only load them once per session, making tests much faster

Pending items:

• Change event handler documentation to explain when the different schema versions are generated
• Updated Bedrock Agents documentation to explain why it will not work if you use Pydantic v2 (Agents for Amazon Bedrock seems to only support 3.0.x OpenAPI schemas) moved this checklist to the Bedrock Agents PR
• Upgrade Swagger-UI to support 3.1 OpenAPI schemas

User experience

Please share what the user experience looks like before and after this change

After this change, the generated OpenAPI schema should always validate correctly against the official schemas

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.

[kbakk]

@rubenfonseca Note that the swagger-ui version that aws-lambda-powertools ships (4.x) doesn't support OpenAPI schema version 3.1.x – you'll get an error when using it (the entire ui is inaccessible):

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

It does seem like passing swagger_base_url="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.8" to enable_swagger mitigates this (swagger-ui is then showing), so you might want to consider updating swagger-ui as well.

See compatibility table here: https://github.com/swagger-api/swagger-ui?tab=readme-ov-file#compatibility

[rubenfonseca]

@rubenfonseca Note that the swagger-ui version that aws-lambda-powertools ships (4.x) doesn't support OpenAPI schema version 3.1.x – you'll get an error when using it (the entire ui is inaccessible):

Please indicate a valid Swagger or OpenAPI version field. Supported version fields are swagger: "2.0" and those that match openapi: 3.0.n (for example, openapi: 3.0.0).

It does seem like passing swagger_base_url="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/5.11.8" to enable_swagger mitigates this (swagger-ui is then showing), so you might want to consider updating swagger-ui as well.

See compatibility table here: swagger-api/swagger-ui?tab=readme-ov-file#compatibility

This is awesome feedback, thank you so much @kbakk !

[rubenfonseca]

I've updated Swagger-UI to 5.x and verified that it works when using Pydantic v2 (which generated a 3.1.0 schema). @leandrodamascena this is now ready for review

[leandrodamascena]

Hey @rubenfonseca! I left some comments and we need to resolve them before I review this PR again and merge. Thanks for fixing this issue.

[sonarcloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarCloud

[leandrodamascena]

APPROVED!