Improve authorization docs #4405
Conversation
packages/authorization/README.md
Outdated
| @@ -28,26 +16,105 @@ npm install --save @loopback/authorization | |||
|
|
|||
| ## Basic use | |||
|
|
|||
| Start by decorating your controller methods with `@authorize` to require the | |||
| request to be authorized. | |||
| The following example shows the basic use of authorize decorator, authorizer and | |||
There was a problem hiding this comment.
nitpick: maybe authorize decorator -> @authorize decorator ?
| The following example shows the basic use of authorize decorator, authorizer and | ||
| authorization component by authorizing a client according to its role: | ||
|
|
||
| ASSUMING your app uses jwt as the authentication strategy, and the user |
There was a problem hiding this comment.
hmm, I was intended to emphasize the assumption, that's why I make them all upper case
|
|
||
| In this example, we make the user profile available via dependency injection | ||
| using a key available from `@loopback/authorization` package. | ||
| First **define `role` as a property in your User model** so that after a user |
There was a problem hiding this comment.
Would using a numbered list be better than "first, then, ... finally"?
|
|
||
| Here is the use case and diagram for the example: | ||
|
|
||
|  |
There was a problem hiding this comment.
I think it would be more helpful if the use case diagram shows the flow of the sequence. I've created a very preliminary diagram of what I have in mind:
There was a problem hiding this comment.
I put the "endpoint" and "controller method" as text, and added your diagram to demo the use case
packages/authorization/README.md
Outdated
|
|
||
|  | ||
|
|
||
|  |
There was a problem hiding this comment.
It would certainly be helpful to include some explanation on what each box means.
There was a problem hiding this comment.
I intended to keep the title in each box brief :) Added explanation: The diagram shows authorization artifacts' responsibilities.
jannyHou
force-pushed
the
authorization/fix-doc
branch
from
93148b0
to
cdb6c13
Compare
There was a problem hiding this comment.
In the code snippet under "Summary and Diagram" section, there's a special character between the 2 decorators. Could you please look into it? Other than that, LGTM.
@authenticate(‘jwt’)�@authorize({allowRoles: ['ADMIN']})
jannyHou
force-pushed
the
authorization/fix-doc
branch
from
cdb6c13
to
829342c
Compare
jannyHou
force-pushed
the
authorization/fix-doc
branch
from
829342c
to
e9fc52b
Compare
Clarify the readme file with a basic example
Base on the discussion in #4291, the basic use example in the readme file is too simple. This PR aims to improve it.
See my comment in #4291 (comment)
Checklist
👉 Read and sign the CLA (Contributor License Agreement) 👈
npm testpasses on your machinepackages/cliwere updatedexamples/*were updated👉 Check out how to submit a PR 👈