feat(event-handler): add description to request body in OpenAPI schema (#3548)

Author: rubenfonseca

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}

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()