Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve authorization docs #4405

Merged
merged 1 commit into from Jan 13, 2020
Merged

Improve authorization docs #4405

merged 1 commit into from Jan 13, 2020

Conversation

@jannyHou
Copy link
Contributor

jannyHou commented Jan 10, 2020

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 test passes on your machine
  • New tests added or existing tests modified to cover all changes
  • Code conforms with the style guide
  • API Documentation in code was updated
  • Documentation in /docs/site was updated
  • Affected artifact templates in packages/cli were updated
  • Affected example projects in examples/* were updated

馃憠 Check out how to submit a PR 馃憟

Copy link
Member

dhmlau left a comment

Thanks for improving the docs. I have some comments especially on the diagrams. Thanks.

@@ -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

This comment has been minimized.

Copy link
@dhmlau

dhmlau Jan 10, 2020

Member

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

This comment has been minimized.

Copy link
@dhmlau

dhmlau Jan 10, 2020

Member

ASSUMING -> Assuming?

This comment has been minimized.

Copy link
@jannyHou

jannyHou Jan 13, 2020

Author Contributor

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

This comment has been minimized.

Copy link
@dhmlau

dhmlau Jan 10, 2020

Member

Would using a numbered list be better than "first, then, ... finally"?

Here is the use case and diagram for the example:
![Use case](imgs/use-case.png)

This comment has been minimized.

Copy link
@dhmlau

dhmlau Jan 10, 2020

Member

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:
Screen Shot 2020-01-10 at 3 58 58 PM

This comment has been minimized.

Copy link
@jannyHou

jannyHou Jan 13, 2020

Author Contributor

I put the "endpoint" and "controller method" as text, and added your diagram to demo the use case

![Use case](imgs/use-case.png)
![Example diagram](imgs/example-diagram.png)

This comment has been minimized.

Copy link
@dhmlau

dhmlau Jan 10, 2020

Member

It would certainly be helpful to include some explanation on what each box means.

This comment has been minimized.

Copy link
@jannyHou

jannyHou Jan 13, 2020

Author Contributor

I intended to keep the title in each box brief :) Added explanation: The diagram shows authorization artifacts' responsibilities.

Copy link
Member

hacksparrow left a comment

Looks good after addressing Diana's feedback.

@jannyHou jannyHou force-pushed the authorization/fix-doc branch from 93148b0 to cdb6c13 Jan 13, 2020
@dhmlau
dhmlau approved these changes Jan 13, 2020
Copy link
Member

dhmlau left a 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(鈥榡wt鈥)锟@authorize({allowRoles: ['ADMIN']})

@jannyHou jannyHou force-pushed the authorization/fix-doc branch from cdb6c13 to 829342c Jan 13, 2020
@jannyHou jannyHou force-pushed the authorization/fix-doc branch from 829342c to e9fc52b Jan 13, 2020
@jannyHou jannyHou merged commit 52a6d71 into master Jan 13, 2020
59 checks passed
59 checks passed
Travis CI - Pull Request Build Passed
Details
clahub All contributors have signed the Contributor License Agreement.
Details
continuous-integration/appveyor/pr AppVeyor build succeeded
Details
coverage/coveralls Coverage increased (+0.003%) to 92.3%
Details
security/snyk - acceptance/repository-cloudant/package.json (StrongLoop) No manifest changes detected
security/snyk - acceptance/repository-mongodb/package.json (StrongLoop) No manifest changes detected
security/snyk - acceptance/repository-mysql/package.json (StrongLoop) No manifest changes detected
security/snyk - acceptance/repository-postgresql/package.json (StrongLoop) No new issues
Details
security/snyk - benchmark/package.json (StrongLoop) No new issues
Details
security/snyk - docs/package.json (StrongLoop) No manifest changes detected
security/snyk - examples/context/package.json (StrongLoop) No new issues
Details
security/snyk - examples/express-composition/package.json (StrongLoop) No new issues
Details
security/snyk - examples/greeter-extension/package.json (StrongLoop) No new issues
Details
security/snyk - examples/greeting-app/package.json (StrongLoop) No new issues
Details
security/snyk - examples/hello-world/package.json (StrongLoop) No new issues
Details
security/snyk - examples/lb3-application/package.json (StrongLoop) No new issues
Details
security/snyk - examples/log-extension/package.json (StrongLoop) No new issues
Details
security/snyk - examples/metrics-prometheus/package.json (StrongLoop) No new issues
Details
security/snyk - examples/rpc-server/package.json (StrongLoop) No new issues
Details
security/snyk - examples/soap-calculator/package.json (StrongLoop) No new issues
Details
security/snyk - examples/todo-list/package.json (StrongLoop) No new issues
Details
security/snyk - examples/todo/package.json (StrongLoop) No new issues
Details
security/snyk - extensions/authentication-passport/package.json (StrongLoop) No manifest changes detected
security/snyk - extensions/health/package.json (StrongLoop) No manifest changes detected
security/snyk - extensions/metrics/package.json (StrongLoop) No manifest changes detected
security/snyk - package.json (StrongLoop) No new issues
Details
security/snyk - packages/authentication/package.json (StrongLoop) No new issues
Details
security/snyk - packages/authorization/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/boot/package.json (StrongLoop) No new issues
Details
security/snyk - packages/boot/src/__tests__/fixtures/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/booter-lb3app/package.json (StrongLoop) No new issues
Details
security/snyk - packages/build/package.json (StrongLoop) No new issues
Details
security/snyk - packages/build/test/integration/fixtures/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/cli/package.json (StrongLoop) No new issues
Details
security/snyk - packages/context/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/core/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/eslint-config/package.json (StrongLoop) No new issues
Details
security/snyk - packages/http-caching-proxy/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/http-server/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/metadata/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/model-api-builder/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/openapi-spec-builder/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/openapi-v3/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/repository-json-schema/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/repository-tests/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/repository/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/rest-crud/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/rest-explorer/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/rest/package.json (StrongLoop) No new issues
Details
security/snyk - packages/security/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/service-proxy/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/testlab/package.json (StrongLoop) No new issues
Details
security/snyk - packages/tsdocs/fixtures/monorepo/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/tsdocs/fixtures/monorepo/packages/pkg1/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/tsdocs/fixtures/monorepo/packages/pkg2/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/tsdocs/fixtures/monorepo/packages/pkg3-non-ts/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/tsdocs/fixtures/monorepo/packages/pkg4-private/package.json (StrongLoop) No manifest changes detected
security/snyk - packages/tsdocs/package.json (StrongLoop) No new issues
Details
security/snyk - sandbox/example/package.json (StrongLoop) No manifest changes detected
@jannyHou jannyHou deleted the authorization/fix-doc branch Jan 13, 2020
@jannyHou jannyHou added this to the Jan 2020 milestone Jan 29, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

4 participants
You can鈥檛 perform that action at this time.