Query parameter descriptions not picked up from docstring?

[flashgorman-chorus]

First check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.
• After submitting this, I commit to one of:
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  • I already hit the "watch" button in this repository to receive notifications and I commit to help at least 2 people that ask questions in the future.
  • Implement a Pull Request for a confirmed bug.

Description

There is a fair amount of talk in FastAPI docs about picking up API descriptions from the docstring. I expected that would include descriptions of query parameter args nested underneath the docstring's Args: block but that does not appear to be the case.

Since the sole purpose of the Args: block is to provide descriptions of args, it seemed quite natural to me that FastAPI would parse this to auto-generate descriptions for each query parameter found so I just wanted to confirm that this is, indeed, the expected behavior:

While FastAPI will pick up your API's description from your docstring, FastAPI will ignore all query parameter descriptions found in the docstring Args: block.

Can anyone here confirm or deny?

[Hultner]

I can confirm that it does not pick up the description from the docstrings.
You can use the description field instead like this:

@app.get("/xyz")
def xyz(
   *,
   param: str = Query(..., description="This will show up in OpenAPI spec",
): ...

[flashgorman-chorus]

Got it. Probably a good enhancement request, for reasons cited above, but will close this issue as the question has been answered. Thank you!

[tiangolo]

Thanks for the help here @Hultner ! 👏 🙇

Thanks for reporting back and closing the issue @flashgorman-chorus 👍

Yep, there are many docstring formats, each with its own micro syntax and none is a "standard", so there's no straightforward way to implement it in a way that is generic enough.

Sorry for the long delay! 🙈 I wanted to personally address each issue/PR and they piled up through time, but now I'm checking each one in order.