UI display in oauth

[winonecheng]

Hi, i try this tool in our api docs in recent days. I think its a great tool including many useful function.

Its our OAS,

securitySchemes:
  oAuth2AuthCode:
    type: oauth2
    description: |
      !! its oAuth2AuthCode's description. !!
    flows:
      authorizationCode:
        authorizationUrl: 'https://account.example.com/oauth2/authorize'
        tokenUrl: 'https://account.example.com/oauth2/token'
        refreshUrl: 'https://account.example.com/oauth2/token'
        scopes: {}
  oAuth2ClientCredentials:
    type: oauth2
    description: |
      !! its oAuth2ClientCredentials' description. !!
    flows:
      clientCredentials:
        tokenUrl: 'https://account.example.com/oauth2/token'
        scopes: {}

and its corresponding UI

Authentication section:

Operation section:

there is some problem:

1. the security scheme name not shown (should be oAuth2AuthCode and oAuth2ClientCredentials)
2. its not easy to identify which oauth flow for an api request to be authorized

If you need more detail, plz let me know 😄

[mrin9]

the security scheme name not shown (should be oAuth2AuthCode and oAuth2ClientCredentials)

security scheme name is an internal name given to the security flows. it is to link the operations with the security flows. It do not add much value in the documentation. People mostly care about which type of flow it is clientCredentials or AuthorizationCode or something else. If you want to display something special for the flow then provide it in the description. In your case if it is important to display security scheme name then put that in the description of the security scheme

its not easy to identify which oauth flow for an api request to be authorized

If an operation has a security requirements, then it is shown in the top-right corner of that operation. For instance I can see from your screenshot(below) that this operation needs two oAuth type of flows. and If need to see what are the two oAuth types, Just hover your mouse on top of the oAuth buttons

In our user-experience survey we found that security / o-auth info for each operation isnt that people look for more often, therefore this info is kept in the corner to allow user to focus on the actual content, also it is a repetitive information and showing it prominently for each operation will make the document look un-necessary bulky and long. If you still feel this info should prominently available for each operation, please provide your reasons and i will take them to our UX team

[winonecheng]

and If need to see what are the two oAuth types, Just hover your mouse on top of the oAuth buttons

Its my hover result below

It doesn't show which flow the operation should use.
In my case, there are some api operations use either clientCredentials or AuthorizationCode, so its better to identify oAuth type

[mrin9]

I thinks thats a valid point, it isn't that clear from the details.
Thanks for providing the screenshots, will take them to our UX designer and see how best we can address this

It doesn't show which flow the operation should use.
In my case, there are some api operations use either clientCredentials or AuthorizationCode, so its better to identify oAuth type

The way you have provided the security details in your spec, it means the operation needs both the oAuth token to work not one of them,
If you need to provide one or the other then you must define them in spec accordingly
refer to this example how various combinations of security can be provided for operations
https://mrin9.github.io/RapiDoc/examples/oauth.html#get-/users/{username}/repositories-3

for instance the below image shows that this operation need 2 security tokens

• An OAuth token (mandatory)
• And an API-Key (either Authorization header or specialKey header )
  

[winonecheng]

If you need to provide one or the other then you must define them in spec

Yes, i define them in all operations. There are two example:

/search:
  get:
    security:
      - oAuth2AuthCode: []
      - oAuth2ClientCredentials: []

and

/me:
  get:
    security:
      - oAuth2AuthCode: []

For /me operation, user can't know which oAuth flow should use, because it just shows security schemes type (oauth) instead of name.

Thanks for your kindly reply. Again, RapiDoc is a great API docs solution!