docs: update 'try it out' section

Update the 'Try it out' section to make use of 'Authorize' button in API Explorer
loopbackio · Oct 4, 2019 · 950b659 · 950b659
1 parent d3b1bf5
commit 950b659
Show file tree

Hide file tree

Showing 5 changed files with 38 additions and 12 deletions.
diff --git a/docs/site/imgs/api_explorer_auth_token_dialog1.png b/docs/site/imgs/api_explorer_auth_token_dialog1.png
diff --git a/docs/site/imgs/api_explorer_auth_token_dialog2.png b/docs/site/imgs/api_explorer_auth_token_dialog2.png
diff --git a/docs/site/imgs/api_explorer_authorize_button.png b/docs/site/imgs/api_explorer_authorize_button.png
diff --git a/docs/site/imgs/api_explorer_usercontroller_section1.png b/docs/site/imgs/api_explorer_usercontroller_section1.png
diff --git a/docs/site/tutorials/authentication/Authentication-Tutorial.md b/docs/site/tutorials/authentication/Authentication-Tutorial.md
@@ -79,11 +79,11 @@ application, follow these steps:
    Try http://[::1]:3000/ping
    ```
 
-2. In a browser, navigate to [http://[::1]:3000](http://127.0.0.1:3000) or
+1. In a browser, navigate to [http://[::1]:3000](http://127.0.0.1:3000) or
    [http://127.0.0.1:3000](http://127.0.0.1:3000), and click on `/explorer` to
    open the `API Explorer`.
 
-3. In the `UserController` section, click on `POST /users`, click on
+1. In the `UserController` section, click on `POST /users`, click on
    `'Try it out'`, specify:
 
    ```ts
@@ -98,7 +98,7 @@ application, follow these steps:
 
    and click on `'Execute'` to **add** a new user named `'User One'`.
 
-4. In the `UserController` section, click on `POST /users/login`, click on
+1. In the `UserController` section, click on `POST /users/login`, click on
    `'Try it out'`, specify:
 
    ```ts
@@ -120,21 +120,43 @@ application, follow these steps:
    }
    ```
 
-5. Perform a `GET` request on the secured endpoint `/users/me` making sure to
-   provide the JWT token in the `Authorization` header. If authentication
-   succeeds, the
+1. Scroll to the top of the API Explorer, and you should see an `Authorize`
+   button. This the place where you can set the JWT token.
+   ![](../../imgs/api_explorer_authorize_button.png)
+
+1. Click on the `Authorize` button, and a dialog opens up.
+   ![](../../imgs/api_explorer_auth_token_dialog1.png)
+
+1. In the `bearerAuth` value field, enter the token string you obtained earlier,
+   and press the `Authorize` button. This JWT token is now available for the
+   `/users/me` endpoint we will interact with next. Press the `Close` button to
+   dismiss the dialog.
+
+   ![](../../imgs/api_explorer_auth_token_dialog2.png)
+
+   {% include note.html content="The <b>Logout</b> button allows you to enter a new value; if needed." %}
+
+1. Scroll down to the `UserController` section to find `GET /users/me`
+   ![](../../imgs/api_explorer_usercontroller_section1.png)
+
+   Notice it has a lock icon and the other endpoints in this section do not.
+   This is because this endpoint specified an operation-level security scheme in
+   the OpenAPI specification. (For details, see the
+   [Specifying the Security Schemes in the OpenApi Specification](#specifying-the-security-schemes-in-the-openapi-specification)
+   section.)
+
+1. Expand the `GET /users/me` section, and click on `Try it out`. There is no
+   data to specify, so simply click on `Execute`. The JWT token you specified
+   earlier was automatically placed in the `Authorization` header of the
+   request.
+
+   If authentication succeeds, the
    [user profile](https://github.com/strongloop/loopback-next/blob/master/packages/authentication/src/types.ts)
    of the currently authenticated user will be returned in the response. If
    authentication fails due to a missing/invalid/expired token, an
    [HTTP 401 UnAuthorized](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401)
    is thrown.
 
-   ```sh
-   curl -X GET \
-   --header 'Authorization: Bearer some.token.value' \
-   http://127.0.0.1:3000/users/me
-   ```
-
    The response is:
 
    ```sh
@@ -943,6 +965,10 @@ export class ShoppingApplication extends BootMixin(
 }
 ```
 
+## Specifying the Security Schemes in the OpenApi Specification
+
+(In progress...)
+
 ## Running the Completed Application
 
 To run the completed application, follow the instructions in the