feat(event_handler): add support for OpenAPI security schemes

[rubenfonseca]

Issue number: #4036

Summary

This PR adds support for OpenAPI security schemes to OpenAPI generation and the Swagger UI.

Changes

Please provide a summary of what's being changed

• Added support for declaring security schemes when generating OpenAPI schemas and when enabling the Swagger UI
• Added support for using those schemas globally or per operation
• Added support for configuring an OAuth2 client when enabling the Swagger UI, and implemented the logic for the OAuth redirect.
• Updated the documentation

User experience

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

For instance, here's how to declare an OAuth2 security scheme globally and test it on Swagger UI:

from aws_lambda_powertools.event_handler import (
    APIGatewayRestResolver,
)
from aws_lambda_powertools.event_handler.openapi.models import (
    OAuth2,
    OAuthFlowAuthorizationCode,
    OAuthFlows,
)
from aws_lambda_powertools.event_handler.openapi.swagger_ui import OAuth2Config

oauth2 = OAuth2Config(
    client_id="xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    app_name="OAuth2 app",
)

app = APIGatewayRestResolver(enable_validation=True)
app.enable_swagger(
    oauth2_config=oauth2,
    security_schemes={
        "oauth": OAuth2(
            flows=OAuthFlows(
                authorizationCode=OAuthFlowAuthorizationCode(
                    authorizationUrl="https://xxx.amazoncognito.com/oauth2/authorize",
                    tokenUrl="https://xxx.amazoncognito.com/oauth2/token",
                ),
            ),
        ),
    },
    security=[{"oauth": []}],
)

TODO

• add tests for the new code
• add support for security schemes in the Swagger UI
• update documentation and examples
• aws_lambda_powertools/event_handler/api_gateway.py:1429:9: C901 get_openapi_schema is too complex (16 > 15)
• aws_lambda_powertools/event_handler/api_gateway.py:1429:9: PLR0912 Too many branches (16 > 15)
• ERROR:xenon:block "aws_lambda_powertools/event_handler/api_gateway.py:1430 get_openapi_schema" has a rank of D
• Fix pydantic v2 tests
• Create a sample to test OAuth2 via Swagger

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.

[rubenfonseca]

@leandrodamascena ready for your review

[rubenfonseca]

@leandrodamascena sorry one last time, there was a logic error and we were always printing the warning

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

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

See analysis details on SonarCloud