feat(event_handler): add support to download OpenAPI spec file (#3571)

Thomas-McKanna · Thomas · leandrodamascena · web-flow · commit 035cf88a6838 · 2024-01-10T09:20:22.000Z
* Add option to download OpenAPI spec file

* Remove Optional from enable_download_spec

Co-authored-by: Leandro Damascena &lt;lcdama@amazon.pt&gt;
Signed-off-by: Thomas McKanna &lt;thomasmckanna@gmail.com&gt;

* Add test for enable_download_spec

* Add test for custom path with enable_download_spec

* Show OpenAPI spec with conditional query string

* Resolving conflicts and minor changes

---------

Signed-off-by: Thomas McKanna &lt;thomasmckanna@gmail.com&gt;
Co-authored-by: Thomas &lt;thomas@Thomass-MacBook-Pro-2.local&gt;
Co-authored-by: Leandro Damascena &lt;lcdama@amazon.pt&gt;
Co-authored-by: Thomas &lt;thomas@Thomass-MBP-2.attlocal.net&gt;
diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py
@@ -1592,6 +1592,7 @@ def enable_swagger(
         middlewares: List[Callable[..., Response]], optional
             List of middlewares to be used for the swagger route.
         """
+        from aws_lambda_powertools.event_handler.openapi.compat import model_json
         from aws_lambda_powertools.event_handler.openapi.models import Server
 
         if not swagger_base_url:
@@ -1640,7 +1641,28 @@ def swagger_handler():
                 license_info=license_info,
             )
 
-            body = generate_swagger_html(spec, swagger_js, swagger_css)
+            # The .replace('</', '<\\/') part is necessary to prevent a potential issue where the JSON string contains
+            # </script> or similar tags. Escaping the forward slash in </ as <\/ ensures that the JSON does not
+            # inadvertently close the script tag, and the JSON remains a valid string within the JavaScript code.
+            escaped_spec = model_json(
+                spec,
+                by_alias=True,
+                exclude_none=True,
+                indent=2,
+            ).replace("</", "<\\/")
+
+            # Check for query parameters; if "format" is specified as "json",
+            # respond with the JSON used in the OpenAPI spec
+            # Example: https://www.example.com/swagger?format=json
+            query_params = self.current_event.query_string_parameters or {}
+            if query_params.get("format") == "json":
+                return Response(
+                    status_code=200,
+                    content_type="application/json",
+                    body=escaped_spec,
+                )
+
+            body = generate_swagger_html(escaped_spec, path, swagger_js, swagger_css)
 
             return Response(
                 status_code=200,
diff --git a/aws_lambda_powertools/event_handler/openapi/swagger_ui/html.py b/aws_lambda_powertools/event_handler/openapi/swagger_ui/html.py
@@ -1,35 +1,19 @@
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from aws_lambda_powertools.event_handler.openapi.models import OpenAPI
-
-
-def generate_swagger_html(spec: "OpenAPI", js_url: str, css_url: str) -> str:
+def generate_swagger_html(spec: str, path: str, js_url: str, css_url: str) -> str:
     """
     Generate Swagger UI HTML page
 
     Parameters
     ----------
-    spec: OpenAPI
+    spec: str
         The OpenAPI spec
+    path: str
+        The path to the Swagger documentation
     js_url: str
         The URL to the Swagger UI JavaScript file
     css_url: str
         The URL to the Swagger UI CSS file
     """
 
-    from aws_lambda_powertools.event_handler.openapi.compat import model_json
-
-    # The .replace('</', '<\\/') part is necessary to prevent a potential issue where the JSON string contains
-    # </script> or similar tags. Escaping the forward slash in </ as <\/ ensures that the JSON does not inadvertently
-    # close the script tag, and the JSON remains a valid string within the JavaScript code.
-    escaped_spec = model_json(
-        spec,
-        by_alias=True,
-        exclude_none=True,
-        indent=2,
-    ).replace("</", "<\\/")
-
     return f"""
 <!DOCTYPE html>
 <html>
@@ -60,7 +44,7 @@ def generate_swagger_html(spec: "OpenAPI", js_url: str, css_url: str) -> str:
     layout: "BaseLayout",
     showExtensions: true,
     showCommonExtensions: true,
-    spec: {escaped_spec},
+    spec: {spec},
     presets: [
       SwaggerUIBundle.presets.apis,
       SwaggerUIBundle.SwaggerUIStandalonePreset
@@ -71,6 +55,7 @@ def generate_swagger_html(spec: "OpenAPI", js_url: str, css_url: str) -> str:
   }}
 
   var ui = SwaggerUIBundle(swaggerUIOptions)
+  ui.specActions.updateUrl('{path}?format=json');
 </script>
 </html>
             """.strip()
diff --git a/tests/functional/event_handler/test_openapi_swagger.py b/tests/functional/event_handler/test_openapi_swagger.py
@@ -1,3 +1,6 @@
+import json
+from typing import Dict
+
 from aws_lambda_powertools.event_handler import APIGatewayRestResolver
 from tests.functional.utils import load_event
 
@@ -68,3 +71,31 @@ def test_openapi_swagger_with_custom_base_url_no_embedded_assets():
     LOAD_GW_EVENT["path"] = "/swagger.js"
     result = app(LOAD_GW_EVENT, {})
     assert result["statusCode"] == 404
+
+
+def test_openapi_swagger_json_view_with_default_path():
+    app = APIGatewayRestResolver(enable_validation=True)
+    app.enable_swagger(title="OpenAPI JSON View")
+    LOAD_GW_EVENT["path"] = "/swagger"
+    LOAD_GW_EVENT["queryStringParameters"] = {"format": "json"}
+
+    result = app(LOAD_GW_EVENT, {})
+
+    assert result["statusCode"] == 200
+    assert result["multiValueHeaders"]["Content-Type"] == ["application/json"]
+    assert isinstance(json.loads(result["body"]), Dict)
+    assert "OpenAPI JSON View" in result["body"]
+
+
+def test_openapi_swagger_json_view_with_custom_path():
+    app = APIGatewayRestResolver(enable_validation=True)
+    app.enable_swagger(path="/fizzbuzz/foobar", title="OpenAPI JSON View")
+    LOAD_GW_EVENT["path"] = "/fizzbuzz/foobar"
+    LOAD_GW_EVENT["queryStringParameters"] = {"format": "json"}
+
+    result = app(LOAD_GW_EVENT, {})
+
+    assert result["statusCode"] == 200
+    assert result["multiValueHeaders"]["Content-Type"] == ["application/json"]
+    assert isinstance(json.loads(result["body"]), Dict)
+    assert "OpenAPI JSON View" in result["body"]
