From 4f7fadb5a0be295103024202584cd3aaf0b9ef62 Mon Sep 17 00:00:00 2001
From: Ruben Fonseca <rubefons@amazon.com>
Date: Thu, 21 Dec 2023 15:12:05 +0100
Subject: [PATCH] feat(event-handler): add description to request body in
 OpenAPI schema (#3548)

---
 .../event_handler/api_gateway.py              |  3 +++
 .../event_handler/test_openapi_params.py      | 24 +++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py
index 19082fd0955..79e194e3719 100644
--- a/aws_lambda_powertools/event_handler/api_gateway.py
+++ b/aws_lambda_powertools/event_handler/api_gateway.py
@@ -617,6 +617,9 @@ def _openapi_operation_request_body(
         if required:
             request_body_oai["required"] = required
 
+        if field_info.description:
+            request_body_oai["description"] = field_info.description
+
         # Generate the request body media type
         request_media_content: Dict[str, Any] = {"schema": body_schema}
         request_body_oai["content"] = {request_media_type: request_media_content}
diff --git a/tests/functional/event_handler/test_openapi_params.py b/tests/functional/event_handler/test_openapi_params.py
index 702bb937571..0f06524ea6d 100644
--- a/tests/functional/event_handler/test_openapi_params.py
+++ b/tests/functional/event_handler/test_openapi_params.py
@@ -349,6 +349,30 @@ def handler(user: Annotated[User, Body(embed=True)]):
     assert body_post_handler_schema.properties["user"].ref == "#/components/schemas/User"
 
 
+def test_openapi_with_body_description():
+    app = APIGatewayRestResolver()
+
+    class User(BaseModel):
+        name: str
+
+    @app.post("/users")
+    def handler(user: Annotated[User, Body(description="This is a user")]):
+        print(user)
+
+    schema = app.get_openapi_schema()
+    assert len(schema.paths.keys()) == 1
+
+    post = schema.paths["/users"].post
+    assert post.parameters is None
+    assert post.requestBody is not None
+
+    request_body = post.requestBody
+
+    # Description should appear in two places: on the request body and on the schema
+    assert request_body.description == "This is a user"
+    assert request_body.content[JSON_CONTENT_TYPE].schema_.description == "This is a user"
+
+
 def test_openapi_with_excluded_operations():
     app = APIGatewayRestResolver()