add formal test

Author: Mathieu Hinderyckx

aws_lambda_powertools/event_handler/api_gateway.py

@@ -85,12 +85,12 @@
     )
     from aws_lambda_powertools.event_handler.openapi.models import (
         Contact,
+        ExternalDocumentation,
         License,
         OpenAPI,
         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 (
@@ -1816,10 +1816,12 @@ 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,
         }
 
+        if external_documentation:
+            output["external_docs"] = external_documentation
+
         components: dict[str, dict[str, Any]] = {}
         paths: dict[str, dict[str, Any]] = {}
         operation_ids: set[str] = set()

tests/functional/event_handler/_pydantic/test_openapi_external_documentation.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from aws_lambda_powertools.event_handler.api_gateway import APIGatewayRestResolver
+from aws_lambda_powertools.event_handler.openapi.models import ExternalDocumentation, Server
+
+
+def test_openapi_schema_no_external_documentation():
+    app = APIGatewayRestResolver()
+
+    schema = app.get_openapi_schema(title="Hello API", version="1.0.0")
+    assert not schema.externalDocs
+
+
+def test_openapi_schema_external_documentation():
+    app = APIGatewayRestResolver()
+
+    schema = app.get_openapi_schema(
+        title="Hello API",
+        version="1.0.0",
+        external_documentation=ExternalDocumentation(
+            description="Find out more about this API",
+            url="https://example.org/docs",
+        ),
+    )
+
+    assert schema.externalDocs
+    assert schema.externalDocs.description == "Find out more about this API"
+    assert schema.externalDocs.url == "https://example.org/docs"