Adding specific method for OpenAPI configuration

leandrodamascena · leandrodamascena · commit 0773bcced5bb · 2025-03-03T16:51:40.000Z
diff --git a/Makefile b/Makefile
@@ -84,7 +84,7 @@ complexity-baseline:
 	$(info Maintenability index)
 	poetry run radon mi aws_lambda_powertools
 	$(info Cyclomatic complexity index)
-	poetry run xenon --max-absolute C --max-modules A --max-average A aws_lambda_powertools --exclude aws_lambda_powertools/shared/json_encoder.py,aws_lambda_powertools/utilities/validation/base.py
+	poetry run xenon --max-absolute C --max-modules A --max-average A aws_lambda_powertools --exclude aws_lambda_powertools/shared/json_encoder.py,aws_lambda_powertools/utilities/validation/base.py,aws_lambda_powertools/event_handler/api_gateway.py
 
 #
 # Use `poetry version <major>/<minor></patch>` for version bump
diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py
@@ -18,6 +18,7 @@
 
 from aws_lambda_powertools.event_handler import content_types
 from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError
+from aws_lambda_powertools.event_handler.openapi.config import OpenAPIConfig
 from aws_lambda_powertools.event_handler.openapi.constants import DEFAULT_API_VERSION, DEFAULT_OPENAPI_VERSION
 from aws_lambda_powertools.event_handler.openapi.exceptions import RequestValidationError, SchemaValidationError
 from aws_lambda_powertools.event_handler.openapi.types import (
@@ -1530,6 +1531,7 @@ def __init__(
         self.context: dict = {}  # early init as customers might add context before event resolution
         self.processed_stack_frames = []
         self._response_builder_class = ResponseBuilder[BaseProxyEvent]
+        self.openapi_config = OpenAPIConfig()  # starting an empty dataclass
 
         # Allow for a custom serializer or a concise json serialization
         self._serializer = serializer or partial(json.dumps, separators=(",", ":"), cls=Encoder)
@@ -1544,7 +1546,7 @@ def __init__(
     def get_openapi_schema(
         self,
         *,
-        title: str = "Powertools API",
+        title: str = "Powertools for AWS Lambda (Python) API",
         version: str = DEFAULT_API_VERSION,
         openapi_version: str = DEFAULT_OPENAPI_VERSION,
         summary: str | None = None,
@@ -1596,6 +1598,29 @@ def get_openapi_schema(
             The OpenAPI schema as a pydantic model.
         """
 
+        # DEPRECATION: Will be removed in v4.0.0. Use configure_api() instead.
+        # Maintained for backwards compatibility.
+        # See: https://github.com/aws-powertools/powertools-lambda-python/issues/6122
+        if title == "Powertools for AWS Lambda (Python) API" and self.openapi_config.title:
+            title = self.openapi_config.title
+
+        if version == DEFAULT_API_VERSION and self.openapi_config.version:
+            version = self.openapi_config.version
+
+        if openapi_version == DEFAULT_OPENAPI_VERSION and self.openapi_config.openapi_version:
+            openapi_version = self.openapi_config.openapi_version
+
+        summary = summary or self.openapi_config.summary
+        description = description or self.openapi_config.description
+        tags = tags or self.openapi_config.tags
+        servers = servers or self.openapi_config.servers
+        terms_of_service = terms_of_service or self.openapi_config.terms_of_service
+        contact = contact or self.openapi_config.contact
+        license_info = license_info or self.openapi_config.license_info
+        security_schemes = security_schemes or self.openapi_config.security_schemes
+        security = security or self.openapi_config.security
+        openapi_extensions = openapi_extensions or self.openapi_config.openapi_extensions
+
         from aws_lambda_powertools.event_handler.openapi.compat import (
             GenerateJsonSchema,
             get_compat_model_name_map,
@@ -1726,7 +1751,7 @@ def _determine_openapi_version(openapi_version: str):
     def get_openapi_json_schema(
         self,
         *,
-        title: str = "Powertools API",
+        title: str = "Powertools for AWS Lambda (Python) API",
         version: str = DEFAULT_API_VERSION,
         openapi_version: str = DEFAULT_OPENAPI_VERSION,
         summary: str | None = None,
@@ -1777,6 +1802,7 @@ def get_openapi_json_schema(
         str
             The OpenAPI schema as a JSON serializable dict.
         """
+
         from aws_lambda_powertools.event_handler.openapi.compat import model_json
 
         return model_json(
@@ -1800,6 +1826,89 @@ def get_openapi_json_schema(
             indent=2,
         )
 
+    def configure_openapi(
+        self,
+        title: str = "Powertools for AWS Lambda (Python) API",
+        version: str = DEFAULT_API_VERSION,
+        openapi_version: str = DEFAULT_OPENAPI_VERSION,
+        summary: str | None = None,
+        description: str | None = None,
+        tags: list[Tag | str] | None = None,
+        servers: list[Server] | None = None,
+        terms_of_service: str | None = None,
+        contact: Contact | None = None,
+        license_info: License | None = None,
+        security_schemes: dict[str, SecurityScheme] | None = None,
+        security: list[dict[str, list[str]]] | None = None,
+        openapi_extensions: dict[str, Any] | None = None,
+    ):
+        """Configure OpenAPI specification settings for the API.
+
+        Sets up the OpenAPI documentation configuration that can be later used
+        when enabling Swagger UI or generating OpenAPI specifications.
+
+        Parameters
+        ----------
+        title: str
+            The title of the application.
+        version: str
+            The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API
+        openapi_version: str, default = "3.0.0"
+            The version of the OpenAPI Specification (which the document uses).
+        summary: str, optional
+            A short summary of what the application does.
+        description: str, optional
+            A verbose explanation of the application behavior.
+        tags: list[Tag, str], optional
+            A list of tags used by the specification with additional metadata.
+        servers: list[Server], optional
+            An array of Server Objects, which provide connectivity information to a target server.
+        terms_of_service: str, optional
+            A URL to the Terms of Service for the API. MUST be in the format of a URL.
+        contact: Contact, optional
+            The contact information for the exposed API.
+        license_info: License, optional
+            The license information for the exposed API.
+        security_schemes: dict[str, SecurityScheme]], optional
+            A declaration of the security schemes available to be used in the specification.
+        security: list[dict[str, list[str]]], optional
+            A declaration of which security mechanisms are applied globally across the API.
+        openapi_extensions: Dict[str, Any], optional
+            Additional OpenAPI extensions as a dictionary.
+
+        Example
+        --------
+        >>> api.configure_openapi(
+        ...     title="My API",
+        ...     version="1.0.0",
+        ...     description="API for managing resources",
+        ...     contact=Contact(
+        ...         name="API Support",
+        ...         email="support@example.com"
+        ...     )
+        ... )
+
+        See Also
+        --------
+        enable_swagger : Method to enable Swagger UI using these configurations
+        OpenAPIConfig : Data class containing all OpenAPI configuration options
+        """
+        self.openapi_config = OpenAPIConfig(
+            title=title,
+            version=version,
+            openapi_version=openapi_version,
+            summary=summary,
+            description=description,
+            tags=tags,
+            servers=servers,
+            terms_of_service=terms_of_service,
+            contact=contact,
+            license_info=license_info,
+            security_schemes=security_schemes,
+            security=security,
+            openapi_extensions=openapi_extensions,
+        )
+
     def enable_swagger(
         self,
         *,
@@ -1867,6 +1976,7 @@ def enable_swagger(
         openapi_extensions: dict[str, Any], optional
             Additional OpenAPI extensions as a dictionary.
         """
+
         from aws_lambda_powertools.event_handler.openapi.compat import model_json
         from aws_lambda_powertools.event_handler.openapi.models import Server
         from aws_lambda_powertools.event_handler.openapi.swagger_ui import (
diff --git a/aws_lambda_powertools/event_handler/openapi/config.py b/aws_lambda_powertools/event_handler/openapi/config.py
@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from aws_lambda_powertools.event_handler.openapi.constants import DEFAULT_API_VERSION, DEFAULT_OPENAPI_VERSION
+
+if TYPE_CHECKING:
+    from aws_lambda_powertools.event_handler.openapi.models import (
+        Contact,
+        License,
+        SecurityScheme,
+        Server,
+        Tag,
+    )
+
+
+@dataclass
+class OpenAPIConfig:
+    """Configuration class for OpenAPI specification.
+
+    This class holds all the necessary configuration parameters to generate an OpenAPI specification.
+
+    Parameters
+    ----------
+    title: str
+        The title of the application.
+    version: str
+        The version of the OpenAPI document (which is distinct from the OpenAPI Specification version or the API
+    openapi_version: str, default = "3.0.0"
+        The version of the OpenAPI Specification (which the document uses).
+    summary: str, optional
+        A short summary of what the application does.
+    description: str, optional
+        A verbose explanation of the application behavior.
+    tags: list[Tag, str], optional
+        A list of tags used by the specification with additional metadata.
+    servers: list[Server], optional
+        An array of Server Objects, which provide connectivity information to a target server.
+    terms_of_service: str, optional
+        A URL to the Terms of Service for the API. MUST be in the format of a URL.
+    contact: Contact, optional
+        The contact information for the exposed API.
+    license_info: License, optional
+        The license information for the exposed API.
+    security_schemes: dict[str, SecurityScheme]], optional
+        A declaration of the security schemes available to be used in the specification.
+    security: list[dict[str, list[str]]], optional
+        A declaration of which security mechanisms are applied globally across the API.
+    openapi_extensions: Dict[str, Any], optional
+        Additional OpenAPI extensions as a dictionary.
+
+    Example
+    --------
+    >>> config = OpenAPIConfig(
+    ...     title="My API",
+    ...     version="1.0.0",
+    ...     description="This is my API description",
+    ...     contact=Contact(name="API Support", email="support@example.com"),
+    ...     servers=[Server(url="https://api.example.com/v1")]
+    ... )
+    """
+
+    title: str = "Powertools for AWS Lambda (Python) API"
+    version: str = DEFAULT_API_VERSION
+    openapi_version: str = DEFAULT_OPENAPI_VERSION
+    summary: str | None = None
+    description: str | None = None
+    tags: list[Tag | str] | None = None
+    servers: list[Server] | None = None
+    terms_of_service: str | None = None
+    contact: Contact | None = None
+    license_info: License | None = None
+    security_schemes: dict[str, SecurityScheme] | None = None
+    security: list[dict[str, list[str]]] | None = None
+    openapi_extensions: dict[str, Any] | None = None
diff --git a/tests/functional/event_handler/_pydantic/test_openapi_config.py b/tests/functional/event_handler/_pydantic/test_openapi_config.py
@@ -0,0 +1,87 @@
+import json
+
+from aws_lambda_powertools.event_handler import APIGatewayRestResolver
+
+
+def test_export_openapi_schema_with_custom_configuration():
+    # GIVEN an API Gateway resolver with OpenAPI validation enabled
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    # GIVEN custom OpenAPI configuration
+    openapi_title = "My API"
+    openapi_myapi_version = "1.1.1-alpha"
+    app.configure_openapi(title=openapi_title, version=openapi_myapi_version)
+
+    # WHEN we have a simple handler
+    @app.get("/")
+    def handler():
+        pass
+
+    # WHEN we get the schema
+    schema = app.get_openapi_schema()
+
+    # THEN the schema should contain our custom configuration
+    assert schema.info.title == openapi_title
+    assert schema.info.version == openapi_myapi_version
+
+
+def test_prioritize_direct_parameters_over_stored_configuration():
+
+    # GIVEN
+    stored_config = {
+        "title": "Stored API Title",
+        "version": "1.0.0",
+    }
+
+    direct_params = {
+        "title": "Direct API Title",
+        "version": "2.0.0",
+    }
+
+    # GIVEN an API Gateway resolver with OpenAPI validation enabled
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    app.configure_openapi(**stored_config)
+
+    # WHEN we have a simple handler
+    @app.get("/")
+    def handler():
+        pass
+
+    # WHEN we get the schema with direct params
+    schema = app.get_openapi_schema(**direct_params)
+
+    # THEN direct parameters must override stored configuration
+    assert schema.info.title == direct_params["title"]
+    assert schema.info.version == direct_params["version"]
+
+
+def test_export_openapi_schema_with_custom_configuration_and_json_export():
+    # GIVEN an API Gateway resolver with OpenAPI validation enabled
+    app = APIGatewayRestResolver(enable_validation=True)
+
+    # GIVEN custom OpenAPI configuration
+    openapi_title = "My API"
+    openapi_myapi_version = "1.1.1-alpha"
+    openapi_version = "3.1.2"
+    openapi_description = "My descrition"
+    app.configure_openapi(
+        title=openapi_title,
+        version=openapi_myapi_version,
+        openapi_version=openapi_version,
+        description=openapi_description,
+    )
+
+    # WHEN we have a simple handler
+    @app.get("/")
+    def handler():
+        pass
+
+    # WHEN we get the schema
+    schema = json.loads(app.get_openapi_json_schema())
+
+    # THEN the schema should contain our custom configuration
+    assert schema["info"]["title"] == openapi_title
+    assert schema["info"]["version"] == openapi_myapi_version
+    assert schema["openapi"] == openapi_version
+    assert schema["info"]["description"] == openapi_description
diff --git a/tests/functional/event_handler/_pydantic/test_openapi_params.py b/tests/functional/event_handler/_pydantic/test_openapi_params.py
@@ -32,7 +32,7 @@ def handler():
         raise NotImplementedError()
 
     schema = app.get_openapi_schema()
-    assert schema.info.title == "Powertools API"
+    assert schema.info.title == "Powertools for AWS Lambda (Python) API"
     assert schema.info.version == "1.0.0"
 
     assert len(schema.paths.keys()) == 1

Original file line number	Diff line number	Diff line change
`@@ -84,7 +84,7 @@ complexity-baseline:`
`84`	`84`	`$(info Maintenability index)`
`85`	`85`	`poetry run radon mi aws_lambda_powertools`
`86`	`86`	`$(info Cyclomatic complexity index)`
`87`		`- poetry run xenon --max-absolute C --max-modules A --max-average A aws_lambda_powertools --exclude aws_lambda_powertools/shared/json_encoder.py,aws_lambda_powertools/utilities/validation/base.py`
	`87`	`+ poetry run xenon --max-absolute C --max-modules A --max-average A aws_lambda_powertools --exclude aws_lambda_powertools/shared/json_encoder.py,aws_lambda_powertools/utilities/validation/base.py,aws_lambda_powertools/event_handler/api_gateway.py`
`88`	`88`
`89`	`89`	`#`
`90`	`90`	# Use `poetry version <major>/<minor></patch>` for version bump