Use case

I use an API Gateway event handler with validation enabled and I'd like to document various responses my endpoint can return. I can add responses parameter to my endpoint definition, however it's not ideal:

• The OpenAPIResponse type doesn't support all the fields that I could use as per the OpenAPI specification for the response object, especially headers to document HTTP headers I could return to the consumer.
• The content field of the OpenAPIResponse also doesn't support all the fields available for the media type object, especially example/examples to provide example(s) of the response payload.

As OpenAPIResponse is a TypedDict, I can actually provide a dict with additional fields, but in that case it shows type errors in the IDE (VS Code in my case) which I have to suppress with # type: ignore. Here's an example:

@app.get(
    "/foo",
    responses={
        200: {
            "description": "Successful Response",
            "content": {
                "application/json": {
                    "schema": {"$ref": "#/components/schemas/FooModel"},
                    "examples": {
                        "example1": {...}
                    }  # type: ignore
                }
            }
        }
    }
)
def foo() -> FooModel:
    ...

Also, note that when I want to add examples to the content value, I have to provide schema and rely on the fact that the response model would be added to the OpenAPI schema automatically due to the endpoint function return value annotation. I can't use model because in that case the examples wouldn't be present in the generated OpenAPI schema (see here).

The issue was previously discussed on Discord – https://discord.com/channels/1006478942305263677/1006527338621710376/1266007500336005120.

Solution/User Experience

The proposed user experience can be seen from the following example:

@app.get(
    "/foo",
    responses={
        200: {
            "description": "Successful Response",
            "headers": {...},
            "content": {
                "application/json": {
                    "model": FooModel,
                    "examples": {
                        "example1": {...}
                    }
                }
            }
        }
    }
)
def foo() -> FooModel:
    ...

To summarize:

• I could use any field supported by the OpenAPI specification for the response object.
• I could use a model field with my response's Pydantic model and it would generate the correct OpenAPI schema while retaining other fields supported by the OpenAPI specification for media type object.

Alternative solutions

No response

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET