Enhancement: Generate OpenAPI parameter descriptions from handler docstrings

[Keating950]

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

---

Note

While we are open for sponsoring on GitHub Sponsors and
OpenCollective, we also utilize Polar.sh to engage in pledge-based sponsorship.

Check out all issues funded or available for funding on our Polar.sh dashboard

• If you would like to see an issue prioritized, make a pledge towards it!
• We receive the pledge once the issue is completed & verified
• This, along with engagement in the community, helps us know which features are a priority to our users.

[provinzkraut]

Interesting idea. Rst parsing is a bit tricky, but maybe for this simple case we can get away with regexing it? 👀

@JacobCoffee

[provinzkraut]

We might also be able to leverage griffe. It supports most of the common docstring formats.