Repository navigation
UI display in oauth #200
Description
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:
- the security scheme name not shown (should be oAuth2AuthCode and oAuth2ClientCredentials)
- its not easy to identify which oauth flow for an api request to be authorized
If you need more detail, plz let me know 😄
Activity
[-]Oauth: Display description field of security scheme and name of security requirement[/-][+]Oauth UI display[/+][-]Oauth UI display[/-][+]UI display in oauth[/+]mrin9 commentedon Apr 30, 2020
security scheme nameis 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 isclientCredentialsorAuthorizationCodeor 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 displaysecurity scheme namethen put that in the description of the security schemeIf 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
oAuthtype of flows. and If need to see what are the two oAuth types, Just hover your mouse on top of the oAuth buttonsIn our user-experience survey we found that
security / o-authinfo 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 teamwinonecheng commentedon May 1, 2020
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
clientCredentialsorAuthorizationCode, so its better to identifyoAuthtypemrin9 commentedon May 1, 2020
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
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
Authorizationheader orspecialKeyheader )winonecheng commentedon May 1, 2020
Yes, i define them in all operations. There are two example:
and
For
/meoperation, user can't know whichoAuthflow 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!