Merge branch 'docs/uplift-applications-api-doc' into 'master'

Add more information and refactor format of topic

See merge request gitlab-org/gitlab-ce!24212

doc/api/applications.md

 # Applications API
-> [Introduced][ce-8160] in GitLab 10.5
-[ce-8160]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8160
-Only admin user can use the Applications API.
-## Create a application
-Create a application by posting a JSON payload.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8160) in GitLab 10.5.
+Applications API operates on OAuth applications for:
+- [Using GitLab as an authentication provider](../integration/oauth_provider.md).
+- [Allowing access to GitLab resources on a user's behalf](oauth2.md).
+NOTE: **Note:**
+Only admin users can use the Applications API.
+## Create an application
+
+Create an application by posting a JSON payload.
 Returns `200` if the request succeeds.
-```
+```text
 POST /applications
 ```
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `name` | string | yes | The name of the application |
-| `redirect_uri` | string | yes | The redirect URI of the application |
-| `scopes` | string | yes | The scopes of the application |
-```bash
+Parameters:
+
+| Attribute      | Type   | Required | Description                      |
+|:---------------|:-------|:---------|:---------------------------------|
+| `name`         | string | yes      | Name of the application.         |
+| `redirect_uri` | string | yes      | Redirect URI of the application. |
+| `scopes`       | string | yes      | Scopes of the application.       |
+
+Example request:
+```sh
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=MyApplication&redirect_uri=http://redirect.uri&scopes=" https://gitlab.example.com/api/v4/applications
 ```
@@ -42,11 +50,13 @@ Example response:
 List all registered applications.
-```
+```text
 GET /applications
 ```
-```bash
+Example request:
+
+```sh
 curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/applications
 ```
@@ -63,7 +73,8 @@ Example response:
 ]
 ```
-> Note: the `secret` value will not be exposed by this API.
+NOTE: **Note:**
+The `secret` value will not be exposed by this API.
 ## Delete an application
@@ -71,7 +82,7 @@ Delete a specific application.
 Returns `204` if the request succeeds.
-```
+```text
 DELETE /applications/:id
 ```
@@ -79,6 +90,8 @@ Parameters:
 - `id` (required) - The id of the application (not the application_id)
-```bash
+Example request:
+
+```sh
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/applications/:id
 ```

doc/integration/oauth_provider.md

@@ -3,8 +3,11 @@
 This document is about using GitLab as an OAuth authentication service provider
 to sign in to other services.
-If you want to use other OAuth authentication service providers to sign in to
-GitLab, please see the [OAuth2 client documentation](../api/oauth2.md).
+If you want to use:
+
+- Other OAuth authentication service providers to sign in to
+  GitLab, see the [OAuth2 client documentation](omniauth.md).
+- The related API, see [Applications API](../api/applications.md).
 ## Introduction to OAuth
@@ -28,7 +31,7 @@ GitLab supports two ways of adding a new OAuth2 application to an instance. You
 can either add an application as a regular user or add it in the admin area.
 What this means is that GitLab can actually have instance-wide and a user-wide
 applications. There is no difference between them except for the different
-permission levels they are set (user/admin). The default callback URL is 
+permission levels they are set (user/admin). The default callback URL is
 `http://your-gitlab.example.com/users/auth/gitlab/callback`
 ## Adding an application through the profile