ran-isenberg · ran-isenberg · Jan 23, 2024 · Jan 5, 2024 · Jan 5, 2024 · Jan 5, 2024
diff --git a/.github/workflows/main-serverless-service.yml b/.github/workflows/main-serverless-service.yml
@@ -73,9 +73,10 @@ jobs:
       - name: Codecov
         uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d # v3.1.4
         with:
+          token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
-          fail_ci_if_error: false # optional (default = false)
-          verbose: false # optional (default = false)
+          fail_ci_if_error: yes # optional (default = false)
+          verbose: yes # optional (default = false)
       - name: Run E2E tests
         run: make e2e
         env:

diff --git a/.github/workflows/pr-serverless-service.yml b/.github/workflows/pr-serverless-service.yml
@@ -94,9 +94,10 @@ jobs:
       - name: Codecov
         uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d # v3.1.4
         with:
+          token: ${{ secrets.CODECOV_TOKEN }}
           files: ./coverage.xml
-          fail_ci_if_error: false # optional (default = false)
-          verbose: false # optional (default = false)
+          fail_ci_if_error: yes # optional (default = false)
+          verbose: yes # optional (default = false)
       - name: Run E2E tests
         run: make e2e
       - name: Destroy stack

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -26,7 +26,7 @@ repos:
         exclude: "^(?!helpers/)"
   - repo: https://github.com/astral-sh/ruff-pre-commit
     # Ruff version.
-    rev: v0.1.13
+    rev: v0.1.14
     hooks:
       # Run the Ruff linter.
       - id: ruff

diff --git a/Makefile b/Makefile
@@ -52,7 +52,7 @@ integration:
 e2e:
 	poetry run pytest tests/e2e  --cov-config=.coveragerc --cov=service --cov-report xml
 
-pr: deps pre-commit complex lint lint-docs unit deploy coverage-tests e2e
+pr: deps format pre-commit complex lint lint-docs unit deploy coverage-tests e2e
 
 coverage-tests:
 	poetry run pytest tests/unit tests/integration  --cov-config=.coveragerc --cov=service --cov-report xml

diff --git a/README.md b/README.md
@@ -93,6 +93,7 @@ This project aims to reduce cognitive load and answer these questions for you by
 - REST API protected by WAF with four AWS managed rules in production deployment
 - CloudWatch dashboards - High level and low level including CloudWatch alarms
 - Unit, infrastructure, security, integration and end to end tests.
+- Automatically generated OpenAPI endpoint: /swagger with Pydnatic schemas for both requests and responses
 
 
 ## CDK Deployment

diff --git a/cdk/service/api_construct.py b/cdk/service/api_construct.py
@@ -20,16 +20,31 @@ def __init__(self, scope: Construct, id_: str, appconfig_app_name: str, is_produ
         self.lambda_role = self._build_lambda_role(self.api_db.db, self.api_db.idempotency_db)
         self.common_layer = self._build_common_layer()
         self.rest_api = self._build_api_gw()
-        api_resource: aws_apigateway.Resource = self.rest_api.root.add_resource('api').add_resource(constants.GW_RESOURCE)
+        api_resource: aws_apigateway.Resource = self.rest_api.root.add_resource('api')
+        orders_resource = api_resource.add_resource(constants.GW_RESOURCE)
         self.create_order_func = self._add_post_lambda_integration(
-            api_resource, self.lambda_role, self.api_db.db, appconfig_app_name, self.api_db.idempotency_db
+            orders_resource, self.lambda_role, self.api_db.db, appconfig_app_name, self.api_db.idempotency_db
         )
+        self._build_swagger_endpoints(rest_api=self.rest_api, dest_func=self.create_order_func)
         self.monitoring = CrudMonitoring(self, id_, self.rest_api, self.api_db.db, self.api_db.idempotency_db, [self.create_order_func])
 
         if is_production_env:
             # add WAF
             self.waf = WafToApiGatewayConstruct(self, f'{id_}waf', self.rest_api)
 
+    def _build_swagger_endpoints(self, rest_api: aws_apigateway.RestApi, dest_func: _lambda.Function) -> None:
+        # GET /swagger
+        swagger_resource: aws_apigateway.Resource = rest_api.root.add_resource(constants.SWAGGER_RESOURCE)
+        swagger_resource.add_method(http_method='GET', integration=aws_apigateway.LambdaIntegration(handler=dest_func))
+        # GET /swagger.css
+        swagger_resource_css = rest_api.root.add_resource(constants.SWAGGER_CSS_RESOURCE)
+        swagger_resource_css.add_method(http_method='GET', integration=aws_apigateway.LambdaIntegration(handler=dest_func))
+        # GET /swagger.js
+        swagger_resource_js = rest_api.root.add_resource(constants.SWAGGER_JS_RESOURCE)
+        swagger_resource_js.add_method(http_method='GET', integration=aws_apigateway.LambdaIntegration(handler=dest_func))
+
+        CfnOutput(self, id=constants.SWAGGER_URL, value=f'{rest_api.url}swagger').override_logical_id(constants.SWAGGER_URL)
+
     def _build_api_gw(self) -> aws_apigateway.RestApi:
         rest_api: aws_apigateway.RestApi = aws_apigateway.RestApi(
             self,
@@ -92,7 +107,7 @@ def _build_common_layer(self) -> PythonLayerVersion:
         )
 
     def _add_post_lambda_integration(
-        self, api_name: aws_apigateway.Resource, role: iam.Role, db: dynamodb.Table, appconfig_app_name: str, idempotency_table: dynamodb.Table
+        self, api_resource: aws_apigateway.Resource, role: iam.Role, db: dynamodb.Table, appconfig_app_name: str, idempotency_table: dynamodb.Table
     ) -> _lambda.Function:
         lambda_function = _lambda.Function(
             self,
@@ -102,7 +117,7 @@ def _add_post_lambda_integration(
             handler='service.handlers.handle_create_order.lambda_handler',
             environment={
                 constants.POWERTOOLS_SERVICE_NAME: constants.SERVICE_NAME,  # for logger, tracer and metrics
-                constants.POWER_TOOLS_LOG_LEVEL: 'DEBUG',  # for logger
+                constants.POWER_TOOLS_LOG_LEVEL: 'INFO',  # for logger
                 'CONFIGURATION_APP': appconfig_app_name,  # for feature flags
                 'CONFIGURATION_ENV': constants.ENVIRONMENT,  # for feature flags
                 'CONFIGURATION_NAME': constants.CONFIGURATION_NAME,  # for feature flags
@@ -124,5 +139,5 @@ def _add_post_lambda_integration(
         )
 
         # POST /api/orders/
-        api_name.add_method(http_method='POST', integration=aws_apigateway.LambdaIntegration(handler=lambda_function))
+        api_resource.add_method(http_method='POST', integration=aws_apigateway.LambdaIntegration(handler=lambda_function))
         return lambda_function
diff --git a/cdk/service/configuration/configuration_construct.py b/cdk/service/configuration/configuration_construct.py
@@ -29,14 +29,14 @@ def __init__(self, scope: Construct, id_: str, environment: str, service_name: s
         self.config_app = appconfig.Application(
             self,
             id=self.app_name,
-            name=self.app_name,
+            application_name=self.app_name,
         )
 
         self.config_env = appconfig.Environment(
             self,
             id=f'{id_}env',
             application=self.config_app,
-            name=environment,
+            environment_name=environment,
         )
 
         # zero minutes, zero bake, 100 growth all at once

diff --git a/cdk/service/constants.py b/cdk/service/constants.py
@@ -9,6 +9,10 @@
 APIGATEWAY = 'Apigateway'
 MONITORING_TOPIC = 'MonitoringTopic'
 GW_RESOURCE = 'orders'
+SWAGGER_RESOURCE = 'swagger'
+SWAGGER_CSS_RESOURCE = 'swagger.css'
+SWAGGER_JS_RESOURCE = 'swagger.js'
+SWAGGER_URL = 'SwaggerURL'
 LAMBDA_LAYER_NAME = 'common'
 API_HANDLER_LAMBDA_MEMORY_SIZE = 128  # MB
 API_HANDLER_LAMBDA_TIMEOUT = 10  # seconds

diff --git a/docs/index.md b/docs/index.md
@@ -46,6 +46,7 @@ This project aims to reduce cognitive load and answer these questions for you by
 - Idempotent API
 - REST API protected by WAF with four AWS managed rules in production deployment
 - Unit, infrastructure, security, integration and E2E tests.
+- Automatically generated OpenAPI endpoint: /swagger with Pydnatic schemas for both requests and responses
 
 The GitHub template project can be found at [https://github.com/ran-isenberg/aws-lambda-handler-cookbook](https://github.com/ran-isenberg/aws-lambda-handler-cookbook){:target="_blank" rel="noopener"}.
 

diff --git a/docs/swagger/openapi.json b/docs/swagger/openapi.json
@@ -0,0 +1,196 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+      "title": "AWS Lambda Handler Cookbook - Orders Service",
+      "version": "1.0.0"
+    },
+    "servers": [
+      {
+        "url": "/prod"
+      }
+    ],
+    "paths": {
+      "/api/orders": {
+        "post": {
+          "tags": [
+            "CRUD"
+          ],
+          "summary": "Create an order",
+          "description": "Create an order identified by the body payload",
+          "operationId": "handle_create_order_api_orders_post",
+          "requestBody": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CreateOrderRequest"
+                }
+              }
+            },
+            "required": true
+          },
+          "responses": {
+            "200": {
+              "description": "The created order",
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/CreateOrderOutput"
+                  }
+                }
+              }
+            },
+            "442": {
+              "description": "Invalid create order request",
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/InvalidRestApiRequest"
+                  }
+                }
+              }
+            },
+            "501": {
+              "description": "Internal server error",
+              "content": {
+                "application/json": {
+                  "schema": {
+                    "$ref": "#/components/schemas/InternalServerErrorOutput"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "components": {
+      "schemas": {
+        "CreateOrderOutput": {
+          "properties": {
+            "name": {
+              "type": "string",
+              "maxLength": 20,
+              "minLength": 1,
+              "title": "Name",
+              "description": "Customer name"
+            },
+            "item_count": {
+              "type": "integer",
+              "exclusiveMinimum": 0.0,
+              "title": "Item Count",
+              "description": "Amount of items in order"
+            },
+            "id": {
+              "type": "string",
+              "maxLength": 36,
+              "minLength": 36,
+              "title": "Id",
+              "description": "Order ID as UUID"
+            }
+          },
+          "type": "object",
+          "required": [
+            "name",
+            "item_count",
+            "id"
+          ],
+          "title": "CreateOrderOutput"
+        },
+        "CreateOrderRequest": {
+          "properties": {
+            "customer_name": {
+              "type": "string",
+              "maxLength": 20,
+              "minLength": 1,
+              "title": "Customer Name",
+              "description": "Customer name"
+            },
+            "order_item_count": {
+              "type": "integer",
+              "exclusiveMinimum": 0.0,
+              "title": "Order Item Count",
+              "description": "Amount of items in order"
+            }
+          },
+          "type": "object",
+          "required": [
+            "customer_name",
+            "order_item_count"
+          ],
+          "title": "CreateOrderRequest"
+        },
+        "InternalServerErrorOutput": {
+          "properties": {
+            "error": {
+              "type": "string",
+              "title": "Error",
+              "description": "Error description",
+              "default": "internal server error"
+            }
+          },
+          "type": "object",
+          "title": "InternalServerErrorOutput"
+        },
+        "InvalidRestApiRequest": {
+          "properties": {
+            "details": {
+              "items": {
+                "$ref": "#/components/schemas/PydanticError"
+              },
+              "type": "array",
+              "title": "Details",
+              "description": "Error details"
+            }
+          },
+          "type": "object",
+          "required": [
+            "details"
+          ],
+          "title": "InvalidRestApiRequest"
+        },
+        "PydanticError": {
+          "properties": {
+            "loc": {
+              "items": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "integer"
+                  }
+                ]
+              },
+              "type": "array",
+              "title": "Loc",
+              "description": "Error location"
+            },
+            "type": {
+              "type": "string",
+              "title": "Type",
+              "description": "Error type"
+            },
+            "msg": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Msg",
+              "description": "Error message"
+            }
+          },
+          "type": "object",
+          "required": [
+            "loc",
+            "type",
+            "msg"
+          ],
+          "title": "PydanticError"
+        }
+      }
+    }
+  }
diff --git a/docs/swagger/swagger.md b/docs/swagger/swagger.md
@@ -0,0 +1,6 @@
+---
+title: Swagger
+description: Swagger Documentation
+---
+
+!!swagger openapi.json!!
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,6 +9,7 @@ nav:
   - Getting Started: getting_started.md
   - CDK: cdk.md
   - Pipeline: pipeline.md
+  - Swagger: swagger/swagger.md
   - Best Practices:
       - best_practices/logger.md
       - best_practices/tracer.md
@@ -80,19 +81,21 @@ copyright: Copyright &copy; 2023 Ran Isenberg
 plugins:
   - git-revision-date
   - search
+  - render_swagger
   - glightbox:
-       touchNavigation: true
-       loop: false
-       effect: zoom
-       slide_effect: slide
-       width: 100%
-       height: auto
-       zoomable: true
-       draggable: true
-       skip_classes:
-         - custom-skip-class-name
-       auto_caption: false
-       caption_position: bottom
+      touchNavigation: true
+      loop: false
+      effect: zoom
+      slide_effect: slide
+      width: 100%
+      height: auto
+      zoomable: true
+      draggable: true
+      skip_classes:
+        - custom-skip-class-name
+      auto_caption: false
+      caption_position: bottom
+
 extra_css:
   - stylesheets/extra.css