feat(event-handler): add compress option when serving Swagger HTML (aws-powertools#3946)

xquek · quekx · leandrodamascena · web-flow · commit 946980d74963 · 2024-03-13T16:32:47.000Z
* Add compress option to enable_swagger

* Adding documentation

---------

Co-authored-by: quekx &lt;quekx@gene.com&gt;
Co-authored-by: Leandro Damascena &lt;lcdama@amazon.pt&gt;
diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py
@@ -1623,6 +1623,7 @@ def enable_swagger(
         license_info: Optional["License"] = None,
         swagger_base_url: Optional[str] = None,
         middlewares: Optional[List[Callable[..., Response]]] = None,
+        compress: bool = False,
     ):
         """
         Returns the OpenAPI schema as a JSON serializable dict
@@ -1655,11 +1656,13 @@ def enable_swagger(
             The base url for the swagger UI. If not provided, we will serve a recent version of the Swagger UI.
         middlewares: List[Callable[..., Response]], optional
             List of middlewares to be used for the swagger route.
+        compress: bool, default = False
+            Whether or not to enable gzip compression swagger route.
         """
         from aws_lambda_powertools.event_handler.openapi.compat import model_json
         from aws_lambda_powertools.event_handler.openapi.models import Server
 
-        @self.get(path, middlewares=middlewares, include_in_schema=False)
+        @self.get(path, middlewares=middlewares, include_in_schema=False, compress=compress)
         def swagger_handler():
             base_path = self._get_base_path()
 
diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md
@@ -524,11 +524,12 @@ Behind the scenes, the [data validation](#data-validation) feature auto-generate
 
 There are some important **caveats** that you should know before enabling it:
 
-| Caveat                                           | Description                                                                                                                                                                              |
+| Caveat                                               | Description                                                                                                                                                                              |
 | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Swagger UI is **publicly accessible by default** | When using `enable_swagger` method, you can [protect sensitive API endpoints by implementing a custom middleware](#customizing-swagger-ui) using your preferred authorization mechanism. |
-| **No micro-functions support** yet               | Swagger UI is enabled on a per resolver instance which will limit its accuracy here.                                                                                                     |
-| You need to expose a **new route**               | You'll need to expose the following path to Lambda: `/swagger`; ignore if you're routing this path already.                         |
+| Swagger UI is **publicly accessible by default**         | When using `enable_swagger` method, you can [protect sensitive API endpoints by implementing a custom middleware](#customizing-swagger-ui) using your preferred authorization mechanism. |
+| **No micro-functions support** yet                       | Swagger UI is enabled on a per resolver instance which will limit its accuracy here.                                                                                                     |
+| You need to expose a **new route**                       | You'll need to expose the following path to Lambda: `/swagger`; ignore if you're routing this path already.                         |
+| JS and CSS  files are **embedded within Swagger HTML**   | If you are not using an external CDN to serve Swagger UI assets, we embed JS and CSS directly into the HTML. To enhance performance, please consider enabling the `compress` option to minimize the size of HTTP requests. |
 
 ```python hl_lines="12-13" title="enabling_swagger.py"
 --8<-- "examples/event_handler_rest/src/enabling_swagger.py"
diff --git a/tests/functional/event_handler/test_openapi_swagger.py b/tests/functional/event_handler/test_openapi_swagger.py
@@ -18,6 +18,18 @@ def test_openapi_swagger():
     assert result["multiValueHeaders"]["Content-Type"] == ["text/html"]
 
 
+def test_openapi_swagger_compressed():
+    app = APIGatewayRestResolver(enable_validation=True)
+    app.enable_swagger(compress=True)
+    LOAD_GW_EVENT["headers"] = {"Accept-Encoding": "gzip, deflate, br"}
+    LOAD_GW_EVENT["path"] = "/swagger"
+    result = app(LOAD_GW_EVENT, {})
+    assert result["statusCode"] == 200
+    assert result["isBase64Encoded"]
+    assert result["multiValueHeaders"]["Content-Type"] == ["text/html"]
+    assert result["multiValueHeaders"]["Content-Encoding"] == ["gzip"]
+
+
 def test_openapi_swagger_with_custom_base_url():
     app = APIGatewayRestResolver(enable_validation=True)
     app.enable_swagger(swagger_base_url="https://aws.amazon.com")
