Enhancement: Generate OpenAPI parameter descriptions from handler docstrings
Summary
When OpenAPIConfig.use_handler_docstrings = True, OpenAPI operation descriptions are automatically generated from handler methods' docstrings. It would be great if this feature could be expand to include parameter descriptions extracted from the reST.
Basic Example
This handler:
@get("/{a:int}/{b:str}")
async def foobar(a: int, b: str) -> str:
"""
Retrieve the specified document.
:param a: The first path parameter.
:param b: The second path parameter.
"""
...Would generate this OpenAPI schema:
{
"paths": {
"/{a}/{b}": {
"get": {
"summary": "Foobar",
"description": "Retrieve the specified document.",
"operationId": "ABFoobar",
"parameters": [
{
"name": "a",
"in": "path",
"schema": {
"type": "integer",
"description": "The first path parameter"
},
"description": "The first path parameter",
},
{
"name": "b",
"in": "path",
"schema": {
"type": "string",
"description": "The second path parameter"
},
"description": "The second path parameter",
}
],
...Drawbacks and Impact
Impacts:
- Would eliminate the need to either duplicate descriptions between docstrings and type annotations or implement an ad-hoc workaround.
Drawbacks:
- Would presumably require adding at least a restructured text parser as a dependency.
Unresolved questions
No response
litestar-org / litestar
Production-ready, Light, Flexible and Extensible ASGI API framework | Effortlessly Build Performant APIs
5.5k
How does funding with Polar work?
1
Pay now to fund the work behind this issue.
2
Get updates on progress being made.
3
Maintainer is rewarded once the issue is completed.
FAQ
Backer
You're funding impactful open source efforts
Contributor
You want to contribute to this effort
Maintainer
You want to get funding like this too