Feature request: Enhance OpenAPIResponse with other fields from OpenAPI specification #4870
Description
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
OpenAPIResponsetype doesn't support all the fields that I could use as per the OpenAPI specification for the response object, especiallyheadersto document HTTP headers I could return to the consumer. - The
contentfield of theOpenAPIResponsealso doesn't support all the fields available for the media type object, especiallyexample/examplesto 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
modelfield 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