Feature Request: ability to define additional response models in OpenAPI

[rubenfonseca]

Discussed in #3540

^{Originally posted by MCR2019 December 19, 2023}
Really excited about the quite new powertools openAPI spec generation so thank to all those who've worked on it and those working on it now :)

I'm trying to get it working for an endpoint and following the documentation on how to specify responses here:
Customizing API Operations docs

Specifically I'd like to add custom reponses which the documentation shows as:

@app.get(
    "/todos/<todo_id>",
    summary="Retrieves a todo item",
    description="Loads a todo item identified by the `todo_id`",
    response_description="The todo object",
    responses={
        200: {"description": "Todo item found"},
        404: {
            "description": "Item not found",
        },
    },
    tags=["Todos"],
)
def get_todo_title(todo_id: int) -> str:
    todo = requests.get(f"https://jsonplaceholder.typicode.com/todos/{todo_id}")
    todo.raise_for_status()

I'd really like to be able to specify the content/schema of the response, maybe as a Pydantic Model which would then generate the response schema in the openAPI spec. (in the same way that the function response type is used).

At the moment I'm only able to get it to work with a basic string which doesn't represent the actual return type/structure.

Is there any more info on what the intention is for how this should be used with a fuller example?

I'm aware that this functionality is quite new so I'm not sure if this is something already on the to do list?

Any info would be great, and thanks again!

[rubenfonseca]

Pasting the comment here:

Hi @MCR2019 this makes sense, FastAPI supports it this way, so we could work on adding support in Powertools too. I'm converting this to a Feature Request ticket!

[rubenfonseca]

@MCR2019 I'm still trying to figure out what the best UX is for this feature, but in the meantime, in case you are blocked by this, here's a workaround:

from typing import Union

from pydantic import BaseModel, Field

from aws_lambda_powertools.event_handler import APIGatewayHttpResolver, Response
from aws_lambda_powertools.event_handler.openapi.types import COMPONENT_REF_PREFIX

app = APIGatewayHttpResolver(enable_validation=True)


class User(BaseModel):
    id_: int = Field(..., alias="id")
    name: str


class Order(BaseModel):
    order_id: int


@app.get(
    "/",
    responses={
        200: {
            "description": "Hello 200",
            "content": {"application/json": {"schema": {"$ref": COMPONENT_REF_PREFIX + "User"}}},
        },
        404: {
            "description": "Hello 404",
            "content": {"application/json": {"schema": {"$ref": COMPONENT_REF_PREFIX + "Order"}}},
        },
    },
)
def put(alternative_return: bool) -> Response[Union[User, Order]]:
    if alternative_return:
        return Response(404, body=Order(order_id=1))
    else:
        return Response(200, body=User(id=3, name="John"))


print(app.get_openapi_json_schema())

[MCR2019]

Thanks for the work around @rubenfonseca :)