Add top-level externalDocs support

Author: Mathieu Hinderyckx

aws_lambda_powertools/event_handler/api_gateway.py

@@ -90,6 +90,7 @@
         SecurityScheme,
         Server,
         Tag,
+        ExternalDocumentation,
     )
     from aws_lambda_powertools.event_handler.openapi.params import Dependant
     from aws_lambda_powertools.event_handler.openapi.swagger_ui.oauth2 import (
@@ -1714,6 +1715,7 @@ def get_openapi_schema(
         license_info: License | None = None,
         security_schemes: dict[str, SecurityScheme] | None = None,
         security: list[dict[str, list[str]]] | None = None,
+        external_documentation: ExternalDocumentation | None = None,
         openapi_extensions: dict[str, Any] | None = None,
     ) -> OpenAPI:
         """
@@ -1745,6 +1747,8 @@ def get_openapi_schema(
             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.
+        external_documentation: ExternalDocumentation, optional
+            Additional external documentation for the API.
         openapi_extensions: Dict[str, Any], optional
             Additional OpenAPI extensions as a dictionary.
 
@@ -1775,6 +1779,7 @@ def get_openapi_schema(
         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
+        external_documentation = external_documentation or self.openapi_config.external_documentation
         openapi_extensions = openapi_extensions or self.openapi_config.openapi_extensions
 
         from pydantic.json_schema import GenerateJsonSchema
@@ -1811,6 +1816,7 @@ def get_openapi_schema(
             "info": info,
             "servers": self._get_openapi_servers(servers),
             "security": self._get_openapi_security(security, security_schemes),
+            "external_docs": external_documentation,
             **openapi_extensions,
         }
 
@@ -1921,6 +1927,7 @@ def get_openapi_json_schema(
         license_info: License | None = None,
         security_schemes: dict[str, SecurityScheme] | None = None,
         security: list[dict[str, list[str]]] | None = None,
+        external_documentation: ExternalDocumentation | None = None,
         openapi_extensions: dict[str, Any] | None = None,
     ) -> str:
         """
@@ -1952,6 +1959,8 @@ def get_openapi_json_schema(
             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.
+        external_documentation: ExternalDocumentation, optional
+            Additional external documentation for the API.
         openapi_extensions: Dict[str, Any], optional
             Additional OpenAPI extensions as a dictionary.
 
@@ -1977,6 +1986,7 @@ def get_openapi_json_schema(
                 license_info=license_info,
                 security_schemes=security_schemes,
                 security=security,
+                external_documentation=external_documentation,
                 openapi_extensions=openapi_extensions,
             ),
             by_alias=True,
@@ -1998,6 +2008,7 @@ def configure_openapi(
         license_info: License | None = None,
         security_schemes: dict[str, SecurityScheme] | None = None,
         security: list[dict[str, list[str]]] | None = None,
+        external_documentation: ExternalDocumentation | None = None,
         openapi_extensions: dict[str, Any] | None = None,
     ):
         """Configure OpenAPI specification settings for the API.
@@ -2031,6 +2042,8 @@ def configure_openapi(
             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.
+        external_documentation: ExternalDocumentation, optional
+            A link to external documentation for the API.
         openapi_extensions: Dict[str, Any], optional
             Additional OpenAPI extensions as a dictionary.
 
@@ -2064,6 +2077,7 @@ def configure_openapi(
             license_info=license_info,
             security_schemes=security_schemes,
             security=security,
+            external_documentation=external_documentation,
             openapi_extensions=openapi_extensions,
         )
 
@@ -2088,6 +2102,7 @@ def enable_swagger(
         security: list[dict[str, list[str]]] | None = None,
         oauth2_config: OAuth2Config | None = None,
         persist_authorization: bool = False,
+        external_documentation: ExternalDocumentation | None = None,
         openapi_extensions: dict[str, Any] | None = None,
     ):
         """
@@ -2131,6 +2146,8 @@ def enable_swagger(
             The OAuth2 configuration for the Swagger UI.
         persist_authorization: bool, optional
             Whether to persist authorization data on browser close/refresh.
+        external_documentation: ExternalDocumentation, optional
+            A link to external documentation for the API.
         openapi_extensions: dict[str, Any], optional
             Additional OpenAPI extensions as a dictionary.
         """
@@ -2183,6 +2200,7 @@ def swagger_handler():
                 license_info=license_info,
                 security_schemes=security_schemes,
                 security=security,
+                external_documentation=external_documentation,
                 openapi_extensions=openapi_extensions,
             )
 

aws_lambda_powertools/event_handler/openapi/config.py

@@ -16,6 +16,7 @@
         SecurityScheme,
         Server,
         Tag,
+        ExternalDocumentation,
     )
 
 
@@ -51,6 +52,8 @@ class OpenAPIConfig:
         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.
+    external_documentation: ExternalDocumentation, optional
+        A link to external documentation for the API.
     openapi_extensions: Dict[str, Any], optional
         Additional OpenAPI extensions as a dictionary.
 
@@ -77,4 +80,5 @@ class OpenAPIConfig:
     license_info: License | None = None
     security_schemes: dict[str, SecurityScheme] | None = None
     security: list[dict[str, list[str]]] | None = None
+    external_documentation: ExternalDocumentation | None = None
     openapi_extensions: dict[str, Any] | None = None