✨ Add support of endpoint return type as response_model

[Tradunsky]

Why this PR is open?

Tl;Dr; Generate endpoint response OpenAPI schema based on the endpoint return type.

In order to declare endpoint params' schema, you can just add typing to a param like this:

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10):
    return fake_items_db[skip : skip + limit]

and it naturally generates OpenAPi spec for parameter types

The same applies to the request body, which is very convenient and feels natural and expected by the principal of least surprise 👍🏻

However, when you add return type - no response schema generated, return schema stays an arbitrary string.

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10) -> List[Item]:
    return Item(fake_items_db[skip : skip + limit])

Unless you specify response_model to generate OpenAPI spec:

@app.get("/items/", response_model=List[Item])
async def read_item(skip: int = 0, limit: int = 10):
    return Item(fake_items_db[skip : skip + limit])

What this PR does?

It aligns behaviour of an endpoint parameter and return type to generate OpenAPI spec.

@app.get("/items/")
async def read_item(skip: int = 0, limit: int = 10) -> List[Item]:
    return Item(fake_items_db[skip : skip + limit])

It is also backward compatible with existing code that has to put response_model in FastAPI route decorator.

How this PR was tested?

pytest tests/test_response_class_is_return_type.py
./scripts/test.sh
and run modified docs_src/query_params/tutorial001.py locally.

WDYT?

[Tradunsky]

oh.. I should have looked at closed PRs, issues and response_model design choice documentation first...

#101
In general, I upvoted for the same arguments people provided in the comments. I think the Principle of least surprise is violated and it is important to fix it, even considering the tradeoff of keeping both response_model and return type hint. it opens the opportunity for better UX and keeps the original solution for any more sophisticated cases like specifying a model with status and description.

Data-wise, it may help to analyze how often people need anything more sophisticated than just one model type. 🤔

Feel free to close this PR though.

[Tradunsky]

Found a lot more discussions about this already.

My opinion still stays the same, but it may be annoying to go over these issues, again and again, so closing this PR.

If anyone finds this, I would recommend looking at the small utility to get this as you need:
https://fastapi-utils.davidmontague.xyz/user-guide/inferring-router/