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.
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:
Would generate this OpenAPI schema:
Drawbacks and Impact
Impacts:
Drawbacks:
Unresolved questions
No response