OAS 3: oauth2 securityScheme -> description does not appear

Q&A

• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

When i set an oauth2 securityScheme the description is not displayed. An info text is displayed about the scopes (i don’t want it to appear)

Example Swagger/OpenAPI definition:

components:
  securitySchemes:
    oAuthSample:
      type: oauth2
      description: I WANT THAT TO BE DISPLAYED !!
      flows:
        implicit: 
          authorizationUrl: https://api.example.com/oauth2/authorize
          scopes:
            read_pets: read your pets
            write_pets: modify pets in your account

Describe the bug you’re encountering

Description doesn’t appear and some infos about scopes are displayed

To reproduce…

Steps to reproduce the behavior:

1. Set a securityScheme like in the standard example
2. Click on Authorize
3. The description is not visible and this text is always displayed: Scopes are used to grant an application different levels of access to data on behalf of the end user. Each API may declare one or more scopes.

API requires the following scopes. Select which ones you want to grant to Swagger UI.

Same behavior if you don’t set any scopes.

Expected behavior

Description should appear Scopes infos should not appear if i don’t want to.

Screenshots

[Keithin8a]

I’m just curious why this issue has been marked as an enhancement. The schema allows it, its just not working. I wonder whether this is why its been nearly a year since this was raised.

Looking at the code here https://github.com/swagger-api/swagger-ui/blob/44acf85d0dbac204733166241548f3197e0d2446/src/core/components/auth/oauth2.jsx#L121

suggests that description is being pulled out it just doesn’t seem to be working. The workaround that we implemented was to put the description at the top level but it makes more sense if it could be in the authorize modal.

[romsDKT]

hi @fh-jashmore,

Thanks for your reply, but what if the description is quite long ? I’ll have to set it in all paths which requires “oAuthSample” authentication, my spec could become a little bit messy.

But as you said, could be a workaround while waiting for a fix.