Open tlinhart opened 3 months ago
Thanks for opening your first issue here! We'll come back to you as soon as we can. In the meantime, check out the #python channel on our Powertools for AWS Lambda Discord: Invite link
Hey @tlinhart! Thanks a lot for opening this issue! I'm adding this to our backlog and expect to work on this early next month.
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:OpenAPIResponse
type doesn't support all the fields that I could use as per the OpenAPI specification for the response object, especiallyheaders
to document HTTP headers I could return to the consumer.content
field of theOpenAPIResponse
also doesn't support all the fields available for the media type object, especiallyexample
/examples
to provide example(s) of the response payload.As
OpenAPIResponse
is aTypedDict
, I can actually provide adict
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:Also, note that when I want to add
examples
to thecontent
value, I have to provideschema
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 usemodel
because in that case theexamples
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:
To summarize:
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