aws-powertools / powertools-lambda-python

A developer toolkit to implement Serverless best practices and increase developer velocity.
https://docs.powertools.aws.dev/lambda/python/latest/
MIT No Attribution
2.88k stars 396 forks source link

Feature request: Enhance `OpenAPIResponse` with other fields from OpenAPI specification #4870

Open tlinhart opened 3 months ago

tlinhart commented 3 months ago

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:

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:

Alternative solutions

No response

Acknowledgment

boring-cyborg[bot] commented 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

leandrodamascena commented 3 months ago

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.