Feature Request: Improve OpenAPI configuration with a common method

[leandrodamascena]

Use case

Our current experience with OpenAPI configuration is not the best. We made a bad decision when designing this feature and are forcing the customer to duplicate code in some cases. If the customer wants to enable swagger and print the OpenAPI schema in the same script, the script should look something like this:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.event_handler.openapi.models import Server

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

app = APIGatewayRestResolver(enable_validation=True)
# ENABLING SWAGGER
app.enable_swagger(path="/swagger", 
                   title="My Api",
                   servers=[Server(url="myurl.com")],
                   security_schemes={
                        "oauth": OAuth2(
                            flows=OAuthFlows(
                                authorizationCode=OAuthFlowAuthorizationCode(
                                    authorizationUrl="https://xxx.amazoncognito.com/oauth2/authorize",
                                    tokenUrl="https://xxx.amazoncognito.com/oauth2/token",
                                ),
                            ),
                        ),
                    },)

@app.get("/todos")
def get_todos() -> int:
    return 1

def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

# EXPORTING OPENAPI SCHEMA
if __name__ == "__main__":
    print(
        app.get_openapi_json_schema(
            title="My API",
            servers=[Server(url="myurl.com")],
            security_schemes={
                "oauth": OAuth2(
                    flows=OAuthFlows(
                        authorizationCode=OAuthFlowAuthorizationCode(
                            authorizationUrl="https://xxx.amazoncognito.com/oauth2/authorize",
                            tokenUrl="https://xxx.amazoncognito.com/oauth2/token",
                        ),
                    ),
                ),
            },
        ),
    )

In addition to customers having to replicate the code everywhere, this introduces additional complexity when defining security_schemes, for example. It is also easy to make a mistake and forget to replicate the code, which can lead to problems.

In addition, this will make things complicated when creating the OpenAPI Schema for multiple Lambda files (coming soon).

Solution/User Experience

Before suggesting the solution I would like to state that we can't make a huge breaking change by removing the fields from both place, so, the solution will consider a new experience but preserving the existent one.

I would like to have a new method called configure_openapi or any other name that we can configure common fields for the OpenAPI specification and make it simple for customers. To avoid any breaking changes, the decision workflow could be as follows:

1 - Parameters will be preserved in the enable_swagger and get_openapi_json_schema methods.
2 - Parameters passed in configure_openapi will take precedence over those passed in enable_swagger and get_openapi_json_schema. configure_openapi is a new method, so customers are doing this intentionally and this is not a breaking change.
3 - If this is not passed in configure_openapi or in enable_swagger/get_openapi_json_schema methods, an error will be thrown in cases where the parameter is required.

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext
from aws_lambda_powertools.event_handler.openapi.models import Server

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

app = APIGatewayRestResolver(enable_validation=True)
# CONFIGURING OPENAPI
app.configure_openapi(title="My Api",
                   servers=[Server(url="myurl.com")],
                   security_schemes={
                        "oauth": OAuth2(
                            flows=OAuthFlows(
                                authorizationCode=OAuthFlowAuthorizationCode(
                                    authorizationUrl="https://xxx.amazoncognito.com/oauth2/authorize",
                                    tokenUrl="https://xxx.amazoncognito.com/oauth2/token",
                                ),
                            ),
                        ),
                    },)

# ENABLING SWAGGER WITH SPECIFIC field for path, since this is specific for SWAGGER
app.enable_swagger(path="/swagger")

@app.get("/todos")
def get_todos() -> int:
    return 1

def lambda_handler(event: dict, context: LambdaContext) -> dict:
    return app.resolve(event, context)

# EXPORTING OPENAPI SCHEMA WITH ALL FIELDS already configured.
if __name__ == "__main__":
    print(
        app.get_openapi_json_schema()
    )

We also need to remove the reference to the fields in the get_openapi_json_schema and enable_swagger methods in our documentation to allow new customers to use the new method, which is a better way to use this utility.

Alternative solutions

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET