a

Author: Ran Isenberg

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

docs/swagger/openapi.json

@@ -0,0 +1,117 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "AWS Lambda Handler Cookbook",
+        "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"
+                                }
+                            }
+                        }
+                    },
+                    "501": {
+                        "description": "internal server error",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "properties": {
+                                        "error": {
+                                            "type": "string",
+                                            "title": "Error",
+                                            "default": "internal server error"
+                                        }
+                                    },
+                                    "type": "object",
+                                    "title": "InternalServerErrorOutput"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "components": {
+        "schemas": {
+            "CreateOrderOutput": {
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "maxLength": 20,
+                        "minLength": 1,
+                        "title": "Name"
+                    },
+                    "item_count": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0,
+                        "title": "Item Count"
+                    },
+                    "id": {
+                        "type": "string",
+                        "maxLength": 36,
+                        "minLength": 36,
+                        "title": "Id"
+                    }
+                },
+                "type": "object",
+                "required": [
+                    "name",
+                    "item_count",
+                    "id"
+                ],
+                "title": "CreateOrderOutput"
+            },
+            "CreateOrderRequest": {
+                "properties": {
+                    "customer_name": {
+                        "type": "string",
+                        "maxLength": 20,
+                        "minLength": 1,
+                        "title": "Customer Name"
+                    },
+                    "order_item_count": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0,
+                        "title": "Order Item Count"
+                    }
+                },
+                "type": "object",
+                "required": [
+                    "customer_name",
+                    "order_item_count"
+                ],
+                "title": "CreateOrderRequest"
+            }
+        }
+    }
+}

docs/swagger/swagger.md

@@ -0,0 +1,6 @@
+---
+title: Swagger
+description: Swagger Documentation
+---
+
+!!swagger openapi.json!!

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,7 @@ copyright: Copyright © 2023 Ran Isenberg
 plugins:
   - git-revision-date
   - search
-  - 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
+  - render_swagger
 extra_css:
   - stylesheets/extra.css
 

pyproject.toml

@@ -55,6 +55,7 @@ mypy = "*"
 types-requests = "*"
 toml = "*"
 poetry-plugin-export = "*"
+mkdocs-render-swagger-plugin = "*"
 
 [tool.pytest.ini_options]
 testpaths = "tests"

service/handlers/handle_create_order.py

@@ -14,7 +14,7 @@
 from service.handlers.utils.rest_api_resolver import ORDERS_PATH, app
 from service.logic.create_order import create_order
 from service.models.input import CreateOrderRequest
-from service.models.output import CreateOrderOutput
+from service.models.output import CreateOrderOutput, InternalServerErrorOutput
 
 
 @app.post(
@@ -23,12 +23,18 @@
     description='Create an order identified by the body payload`',
     response_description='The created order',
     responses={
-        200: CreateOrderOutput.model_json_schema(),
-        501: {'error': 'internal server error'},
+        200: {
+            'description': 'The created order',
+            'content': {'application/json': {'schema': {'$ref': '#/components/schemas/CreateOrderOutput'}}},
+        },
+        501: {
+            'description': 'Internal server error',
+            'content': {'application/json': {'schema': InternalServerErrorOutput.model_json_schema()}},
+        },
     },
-    tags=['CRUD'],
+    tags=['CRUD', 'Orders'],
 )
-def handle_create_order(create_input: Annotated[CreateOrderRequest, Body(embed=False, media_type='application/json')]) -> dict[str, Any]:
+def handle_create_order(create_input: Annotated[CreateOrderRequest, Body(embed=False, media_type='application/json')]) -> CreateOrderOutput:
     env_vars: MyHandlerEnvVars = get_environment_variables(model=MyHandlerEnvVars)
     logger.debug('environment variables', env_vars=env_vars.model_dump())
     logger.info('got create order request', order=create_input.model_dump())
@@ -44,7 +50,7 @@ def handle_create_order(create_input: Annotated[CreateOrderRequest, Body(embed=F
     )
 
     logger.info('finished handling create order request')
-    return response.model_dump()
+    return response
 
 
 @init_environment_variables(model=MyHandlerEnvVars)

service/handlers/utils/rest_api_resolver.py

@@ -1,10 +1,10 @@
-import json
 from http import HTTPStatus
 
 from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response, content_types
 
 from service.handlers.utils.observability import logger
 from service.models.exceptions import DynamicConfigurationException, InternalServerException
+from service.models.output import InternalServerErrorOutput
 
 ORDERS_PATH = '/api/orders/'
 
@@ -16,17 +16,13 @@
 def handle_dynamic_config_error(ex: DynamicConfigurationException):  # receives exception raised
     logger.exception('failed to load dynamic configuration from AppConfig')
     return Response(
-        status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
-        content_type=content_types.APPLICATION_JSON,
-        body=json.dumps({'error': 'internal server error'}),
+        status_code=HTTPStatus.INTERNAL_SERVER_ERROR, content_type=content_types.APPLICATION_JSON, body=InternalServerErrorOutput().model_dump()
     )
 
 
 @app.exception_handler(InternalServerException)
 def handle_internal_server_error(ex: InternalServerException):  # receives exception raised
     logger.exception('finished handling request with internal error')
     return Response(
-        status_code=HTTPStatus.INTERNAL_SERVER_ERROR,
-        content_type=content_types.APPLICATION_JSON,
-        body=json.dumps({'error': 'internal server error'}),
+        status_code=HTTPStatus.INTERNAL_SERVER_ERROR, content_type=content_types.APPLICATION_JSON, body=InternalServerErrorOutput().model_dump()
     )

service/models/output.py

@@ -1,3 +1,5 @@
+from pydantic import BaseModel
+
 from service.models.order import Order
 
 
@@ -6,3 +8,7 @@
 # The output can be a subject of what order contains, i.e just the id
 class CreateOrderOutput(Order):
     pass
+
+
+class InternalServerErrorOutput(BaseModel):
+    error: str = 'internal server error'

tests/e2e/test_create_order.py

@@ -49,7 +49,5 @@ def test_handler_bad_request(api_gw_url):
     # When: Making a POST request to the API Gateway URL
     response = requests.post(api_gw_url, data=body_str)
 
-    # Then: Validate the response status is 400 BAD REQUEST and body is empty
-    assert response.status_code == HTTPStatus.BAD_REQUEST
-    body_dict = json.loads(response.text)
-    assert body_dict == {'error': 'invalid input'}
+    # Then: Validate the response status is 422 UNPROCESSABLE_ENTITY
+    assert response.status_code == HTTPStatus.UNPROCESSABLE_ENTITY

tests/integration/test_create_order.py

@@ -89,6 +89,8 @@ def test_internal_server_error(mocker, table_name: str):
 
         # Then: Ensure the response reflects an internal server error
         assert response['statusCode'] == HTTPStatus.INTERNAL_SERVER_ERROR
+        body_dict = json.loads(response['body'])
+        assert body_dict == {'error': 'internal server error'}
 
 
 def test_handler_bad_request(mocker):