Update api docs to finish aligning EE and CE docs

Squashing a few commits and continuing work
on merging the 12 api docs that have not
been ported to CE yet.

1 files changed, 166 insertions, 22 deletions

diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 85a07589956..69db9f97a35 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -29,27 +29,28 @@ GET /merge_requests?search=foo&in=title
 
 Parameters:
 
-| Attribute           | Type     | Required | Description                                                                                                            |
-| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `state`             | string   | no       | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`                             |
-| `order_by`          | string   | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                |
-| `sort`              | string   | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                     |
-| `milestone`         | string   | no       | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
-| `view`              | string   | no       | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request                              |
-| `labels`            | string   | no       | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
-| `created_after`     | datetime | no       | Return merge requests created on or after the given time                                                               |
-| `created_before`    | datetime | no       | Return merge requests created on or before the given time                                                              |
-| `updated_after`     | datetime | no       | Return merge requests updated on or after the given time                                                               |
-| `updated_before`    | datetime | no       | Return merge requests updated on or before the given time                                                              |
-| `scope`             | string   | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
-| `author_id`         | integer  | no       | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`              |
-| `assignee_id`       | integer  | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
-| `my_reaction_emoji` | string   | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
-| `source_branch`     | string   | no       | Return merge requests with the given source branch                                                                     |
-| `target_branch`     | string   | no       | Return merge requests with the given target branch                                                                     |
-| `search`            | string   | no       | Search merge requests against their `title` and `description`                                                          |
-| `in`                | string   | no       | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
-| `wip`               | string   | no       | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
+| Attribute           | Type           | Required | Description                                                                                                            |
+| ------------------- | --------       | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `state`             | string         | no       | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged`                             |
+| `order_by`          | string         | no       | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at`                                |
+| `sort`              | string         | no       | Return requests sorted in `asc` or `desc` order. Default is `desc`                                                     |
+| `milestone`         | string         | no       | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
+| `view`              | string         | no       | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request                              |
+| `labels`            | string         | no       | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
+| `created_after`     | datetime       | no       | Return merge requests created on or after the given time                                                               |
+| `created_before`    | datetime       | no       | Return merge requests created on or before the given time                                                              |
+| `updated_after`     | datetime       | no       | Return merge requests updated on or after the given time                                                               |
+| `updated_before`    | datetime       | no       | Return merge requests updated on or before the given time                                                              |
+| `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. |
+| `author_id`         | integer        | no       | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me`              |
+| `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. |
+| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
+| `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
+| `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                     |
+| `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                     |
+| `search`            | string         | no       | Search merge requests against their `title` and `description`                                                          |
+| `in`                | string         | no       | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` |
+| `wip`               | string         | no       | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests |
 
 ```json
 [
@@ -147,6 +148,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## List project merge requests
 
 Get all merge requests for this project.
@@ -191,6 +206,7 @@ Parameters:
 | `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ |
 | `author_id`         | integer        | no       | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_                                 |
 | `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
+| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
 | `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
 | `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                             |
 | `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                             |
@@ -293,6 +309,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## List group merge requests
 
 Get all merge requests for this group and its subgroups.
@@ -328,6 +358,7 @@ Parameters:
 | `scope`             | string         | no       | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br>                                     |
 | `author_id`         | integer        | no       | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_                                 |
 | `assignee_id`       | integer        | no       | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ |
+| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. |
 | `my_reaction_emoji` | string         | no       | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ |
 | `source_branch`     | string         | no       | Return merge requests with the given source branch                                                                             |
 | `target_branch`     | string         | no       | Return merge requests with the given target branch                                                                             |
@@ -427,6 +458,20 @@ Parameters:
 ]
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+[
+  {
+    "id": 1,
+    "title": "test1",
+    "approvals_before_merge": null
+    ...
+  }
+]
+```
+
 ## Get single MR
 
 Shows information about a single merge request.
@@ -565,6 +610,18 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Get single MR participants
 
 Get a list of merge request participants.
@@ -767,6 +824,7 @@ Parameters:
 ## Create MR
 
 Creates a new merge request.
+
 ```
 POST /projects/:id/merge_requests
 ```
@@ -788,6 +846,15 @@ POST /projects/:id/merge_requests
 | `allow_maintainer_to_push` | boolean | no       | Deprecated, see allow_collaboration                                             |
 | `squash`                   | boolean | no       | Squash commits into a single commit when merging                                |
 
+If `approvals_before_merge` **[STARTER]** is not provided, it inherits the value from the
+target project. If it is provided, then the following conditions must hold in
+order for it to take effect:
+
+1. The target project's `approvals_before_merge` must be greater than zero. (A
+   value of zero disables approvals for that project.)
+2. The provided value of `approvals_before_merge` must be greater than the
+   target project's `approvals_before_merge`.
+
 ```json
 {
   "id": 1,
@@ -893,6 +960,18 @@ POST /projects/:id/merge_requests
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Update MR
 
 Updates an existing merge request. You can change the target branch, title, or even close the MR.
@@ -1034,6 +1113,18 @@ Must include at least one non-required attribute from above.
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Delete a merge request
 
 Only for admins and project owners. Soft deletes the merge request in question.
@@ -1191,7 +1282,19 @@ Parameters:
 }
 ```
 
-## Returns the up to date merge-ref HEAD commit
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
+## Merge to default merge ref path
 
 Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` 
 ref, of the target project repository, if possible. This ref will have the state the target branch would have if
@@ -1349,6 +1452,18 @@ Parameters:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Rebase a merge request
 
 Automatically rebase the `source_branch` of the merge request against its
@@ -1616,6 +1731,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Unsubscribe from a merge request
 
 Unsubscribes the authenticated user from a merge request to not receive
@@ -1749,6 +1876,18 @@ Example response:
 }
 ```
 
+Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see
+the `approvals_before_merge` parameter:
+
+```json
+{
+  "id": 1,
+  "title": "test1",
+  "approvals_before_merge": null
+  ...
+}
+```
+
 ## Create a todo
 
 Manually creates a todo for the current user on a merge request.
@@ -1970,6 +2109,7 @@ Example response:
   }]
 }
 ```
+
 ## Set a time estimate for a merge request
 
 Sets an estimated time of work for this merge request.
@@ -2114,3 +2254,7 @@ Example response:
 [ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016
 [ce-15454]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15454
 [ce-18935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18935
+
+## Approvals **[STARTER]**
+
+For approvals, please see [Merge Request Approvals](merge_request_approvals.md)