Specify securitySchemes description in OpenAPI

[and-semakin]

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:
  • Read open issues with questions until I find 2 issues where I can help someone and add a comment to help there.
  • Or, 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

According to the OpenAPI scheme, there is an optional description field that can be specified for any authentication type. For example, here it is for OAuth2: https://github.com/OAI/OpenAPI-Specification/blob/42a9e3d4eddade52363a5c4fac852e80681c2fe5/schemas/v3.0/schema.yaml#L831-L832.

If we look at FastAPI's own code, we also find it: https://github.com/tiangolo/fastapi/blob/33be5fc8baa02bae949e1986f1821dae8f84f487/fastapi/openapi/models.py#L258.

Unfortunately, there is no easy way to fill this field for pre-defined security dependencies because none of them accept the description parameter.

Example

from fastapi.security import OAuth2PasswordBearer

AUTH_DESCRIPTION = """
To get a fully-functional access token, you need to pass the `scope`
and `audience` parameters as described below..."""

# what I want to do, but it doesn't work this way
auth = OAuth2PasswordBearer(tokenUrl="...", description=AUTH_DESCRIPTION)

# what I have to do at the moment as a workaround
auth = OAuth2PasswordBearer(tokenUrl="...")
auth.model.description = AUTH_DESCRIPTION

What I want to achieve as a result is the following OpenAPI spec fragment:

  securitySchemes:
    OAuth2PasswordBearer:
      description: '

        To get a fully-functional access token, you need to pass the `scope`

        and `audience` parameters as described below...'
      flows:
        password:
          scopes: {}
          tokenUrl: '...'
      type: oauth2

The solution you would like

All child classes of SecurityBase (i.e. HTTPBase, OAuth2, OpenIdConnect, etc) should accept description as an optional argument in the __init__ method and properly configure its self.model attribute using this description.

Environment

• OS: macOS
• FastAPI Version: 0.62.0
• Python version: 3.8.6

Additional context

Note: there is also a bug in Swagger UI that prevents the description from being shown up. But we at least need to support it on the FastAPI side.

[codespearhead]

@and-semakin This was already handled by #1757 . Can you mark this discussion as answered?