Bug: openAPI generation - operation requestBody description only on schema output, not at higher level needed for html

[MCR2019]

Expected Behaviour

When creating an operation such as a PUT with a body parameter, the body parameter description should be populated on the output at the requestBody level (when generating the spec with app.get_openapi_json_schema() ).

Current Behaviour

When creating an operation such as a PUT with a body parameter, the body parameter description only appears in the output under schema (when generating the spec with app.get_openapi_json_schema() ).

Current output shows requestBody description only at the schema level, this means that when redocly is used to create an html file from the spec the description does not appear.
For the path parameter the descrition is populated at two levels which means it does appear in the redocly generated html.

Current output:

OAS 3.1.0 looks as though it is possible to populate the description on the requestBody object as well:

Code snippet

from typing import Dict, Any

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import Body, Path
from aws_lambda_powertools.shared.types import Annotated

app = APIGatewayRestResolver(enable_validation=True)


@app.put(
    "/example-resource/<path_parameter>",
)
def put(
        path_parameter: Annotated[str, Path(description="test path description appears at schema and higher level", example="example01")],
        event_body: Annotated[Dict[str, Any], Body(description="test body description only appears at schema level")]
):
    pass


if __name__ == "__main__":
    print(app.get_openapi_json_schema())

Possible Solution

Populate description on the requestBody object as well as the schema.

Steps to Reproduce

Create an operation with a request body and add a description to the Body object.
Add a path parameter with a description to the operation.
Note on the output where description is populated in two places for the path parameter and only in one place for the body.
Optional -> Can generate a .html using redocly to confirm which of the descriptions makes it into the generated documentation.

Powertools for AWS Lambda (Python) version

2.30.2

AWS Lambda function runtime

3.10

Packaging format used

PyPi

Debugging logs

No response

[rubenfonseca]

Looking at this now

[rubenfonseca]

Hi @MCR2019 I've tried to use https://redocly.github.io/redoc/ to upload the OpenAPI generated by your code sample, and I see this.

With you change, what would be different in the UI?

[MCR2019]

Hi @rubenfonseca , thanks for taking a look at that so quickly and apologies that my example wasn't as accurate as it could be.

I've had another look at it and updated the requestBody so that it uses a Pydantic schema for the type (which is what I would use to enable validation).

example code is now:

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.event_handler.openapi.params import Body, Path
from aws_lambda_powertools.shared.types import Annotated
from pydantic import BaseModel, Extra, Field

app = APIGatewayRestResolver(enable_validation=True)


class ExamplePayloadSchema(BaseModel):
    """Pydantic example payload schema."""

    example_attribute: str = Field(description="Warning limit for remaining IDs.", format="number")

    class Config:
        """Pydantic model config."""

        extra = Extra.forbid


@app.put(
    "/example-resource/<path_parameter>",
)
def put(
        path_parameter: Annotated[str, Path(description="test path description appears at schema and higher level", example="example01")],
        event_body: Annotated[ExamplePayloadSchema, Body(description="test body description only appears at the schema level")]
):
    pass


if __name__ == "__main__":
    openapi_json_schema = app.get_openapi_json_schema()

    with open("openapi_spec_without.json", "w") as json_spec_file:
        json_spec_file.writelines(openapi_json_schema)

this produces the spec:
openapi_spec_without.json

which when an html file is generated using redoc-cli bundle -o openapi/index_without.html openapi/openapi_spec_without.json looks like this:

(There is no description for the request body)

• Manually updating for desired output:

Manually updating the json spec file to include a description in the requestBody (line 46):
openapi_spec_with.json

and generating html file with redoc-cli bundle -o openapi/index_with.html openapi/openapi_spec_with.json gives an html file which shows a description for the request body:

Hopefully that illustrates the issue more clearly, I'll keep looking into what's going on and add more details if I can.

Thanks

[rubenfonseca]

This helps a lot! Let me see what's missing on our side.