Merge branch 'continuation-of-50878' into 'master'

Normalize API parameters

See merge request gitlab-org/gitlab!75000

doc/api/dora4_project_analytics.md

@@ -25,9 +25,6 @@ GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=:
 | Attribute    | Type   | Required | Description           |
 |--------------|--------|----------|-----------------------|
 | `id`         | string | yes      | The ID of the project |
-
-| Parameter    | Type   | Required | Description           |
-|--------------|--------|----------|-----------------------|
 | `environment`| string | yes      | The name of the environment to filter by |
 | `from`       | string | yes      | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
 | `to`         | string | no       | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |

doc/api/epics.md

@@ -62,7 +62,7 @@ GET /groups/:id/epics?state=opened
 | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user               |
 | `author_id`         | integer          | no         | Return epics created by the given user `id`                                                                                 |
-| `labels`            | string           | no         | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used |
+| `labels`            | string           | no         | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used |
 | `with_labels_details` | boolean        | no         | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later |
 | `order_by`          | string           | no         | Return epics ordered by `created_at`, `updated_at`, or `title` fields. Default is `created_at`                              |
 | `sort`              | string           | no         | Return epics sorted in `asc` or `desc` order. Default is `desc`                                                             |
@@ -265,7 +265,7 @@ POST /groups/:id/epics
 | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user                |
 | `title`             | string           | yes        | The title of the epic |
-| `labels`            | string           | no         | The comma separated list of labels |
+| `labels`            | string           | no         | The comma-separated list of labels |
 | `description`       | string           | no         | The description of the epic. Limited to 1,048,576 characters.  |
 | `confidential`      | boolean          | no         | Whether the epic should be confidential |
 | `created_at`        | string           | no         | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) |

doc/api/feature_flag_user_lists.md

@@ -71,7 +71,7 @@ POST /projects/:id/feature_flags_user_lists
 | ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding).       |
 | `name`              | string           | yes        | The name of the feature flag. |
-| `user_xids`         | string           | yes        | A comma separated list of user IDs. |
+| `user_xids`         | string           | yes        | A comma-separated list of user IDs. |
 
 ```shell
 curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists" \
@@ -143,7 +143,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid
 | `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding).       |
 | `iid`               | integer/string   | yes        | The internal ID of the project's feature flag user list.                               |
 | `name`              | string           | no         | The name of the feature flag.                                                          |
-| `user_xids`         | string           | no         | A comma separated list of user IDs.                                                    |
+| `user_xids`         | string           | no         | A comma-separated list of user IDs.                                                    |
 
 ```shell
 curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists/1" \

doc/api/group_labels.md

@@ -77,7 +77,7 @@ GET /groups/:id/labels/:label_id
 
 | Attribute     | Type           | Required | Description                                                                                                                                                                  |
 | ---------     | ----           | -------- | -----------                                                                                                                                                                  |
-| `id`          | integer/string | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user.                                                               |
+| `id`          | integer or string | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user.                                                               |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. |
 | `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
@@ -152,7 +152,7 @@ PUT /groups/:id/labels/:label_id
 
 | Attribute     | Type    | Required | Description                  |
 | ------------- | ------- | -------- | ---------------------------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 | `new_name`    | string  | no      | The new name of the label        |
 | `color`       | string  | no      | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
@@ -193,7 +193,7 @@ DELETE /groups/:id/labels/:label_id
 
 | Attribute | Type    | Required | Description           |
 | --------- | ------- | -------- | --------------------- |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 
 ```shell
@@ -214,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe
 
 | Attribute  | Type              | Required | Description                          |
 | ---------- | ----------------- | -------- | ------------------------------------ |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes      | The ID or title of a group's label. |
 
 ```shell
@@ -250,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe
 
 | Attribute  | Type              | Required | Description                          |
 | ---------- | ----------------- | -------- | ------------------------------------ |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes      | The ID or title of a group's label. |
 
 ```shell

doc/api/instance_clusters.md

@@ -97,7 +97,6 @@ Example response:
     ...
   }
 ]
-
 ```
 
 ## Get a single instance cluster
@@ -184,7 +183,6 @@ curl --header "Private-Token:<your_access_token>" "http://gitlab.example.com/api
 -H "Accept:application/json" \
 -H "Content-Type:application/json" \
 -X POST --data '{"name":"cluster-3", "environment_scope":"production", "platform_kubernetes_attributes":{"api_url":"https://example.com", "token":"12345",  "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"}}'
-
 ```
 
 Example response:
@@ -255,7 +253,6 @@ Example request:
 curl --header "Private-Token: <your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/9" \
 -H "Content-Type:application/json" \
 -X PUT --data '{"name":"update-cluster-name", "platform_kubernetes_attributes":{"api_url":"https://new-example.com","token":"new-token"}}'
-
 ```
 
 Example response:
@@ -290,7 +287,6 @@ Example response:
   "management_project": null,
   "project": null
 }
-
 ```
 
 ## Delete instance cluster

doc/api/issues_statistics.md

@@ -49,7 +49,7 @@ GET /issues_statistics?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
-| `confidential`     | boolean          | no         | Filter confidential or public issues.                                                                                                               |
+| `confidential`      | boolean          | no         | Filter confidential or public issues.                                                                                                               |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/issues_statistics"
@@ -105,7 +105,7 @@ GET /groups/:id/issues_statistics?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
-| `confidential`     | boolean          | no         | Filter confidential or public issues.                                                                                         |
+| `confidential`      | boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/issues_statistics"
@@ -161,7 +161,7 @@ GET /projects/:id/issues_statistics?confidential=true
 | `created_before`    | datetime         | no         | Return issues created on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_after`     | datetime         | no         | Return issues updated on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
 | `updated_before`    | datetime         | no         | Return issues updated on or before the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
-| `confidential`     | boolean          | no         | Filter confidential or public issues.                                                                                         |
+| `confidential`      | boolean          | no         | Filter confidential or public issues.                                                                                         |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues_statistics"

doc/api/labels.md

@@ -119,7 +119,7 @@ GET /projects/:id/labels/:label_id
 
 | Attribute     | Type           | Required | Description                                                                                                                                                                  |
 | ---------     | -------        | -------- | ---------------------                                                                                                                                                        |
-| `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user                                                              |
+| `id`          | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user                                                              |
 | `label_id` | integer or string | yes | The ID or title of a project's label. |
 | `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. |
 
@@ -195,7 +195,7 @@ DELETE /projects/:id/labels/:label_id
 
 | Attribute | Type    | Required | Description           |
 | --------- | ------- | -------- | --------------------- |
-| `id`            | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`            | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 
 ```shell
@@ -216,7 +216,7 @@ PUT /projects/:id/labels/:label_id
 
 | Attribute       | Type    | Required                          | Description                      |
 | --------------- | ------- | --------------------------------- | -------------------------------  |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 | `new_name`      | string  | yes if `color` is not provided    | The new name of the label        |
 | `color`         | string  | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
@@ -265,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote
 
 | Attribute       | Type    | Required                          | Description                      |
 | --------------- | ------- | --------------------------------- | -------------------------------  |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes | The ID or title of a group's label. |
 
 ```shell
@@ -303,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe
 
 | Attribute  | Type              | Required | Description                          |
 | ---------- | ----------------- | -------- | ------------------------------------ |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes      | The ID or title of a project's label |
 
 ```shell
@@ -341,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe
 
 | Attribute  | Type              | Required | Description                          |
 | ---------- | ----------------- | -------- | ------------------------------------ |
-| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`      | integer or string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `label_id` | integer or string | yes      | The ID or title of a project's label |
 
 ```shell

doc/api/merge_request_context_commits.md

@@ -17,8 +17,10 @@ GET /projects/:id/merge_requests/:merge_request_iid/context_commits
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `merge_request_iid` (required) - The internal ID of the merge request
+| Attribute           | Type    | Required | Description                                                                                                     |
+|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`                | integer | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request                                                                            |
 
 ```json
 [
@@ -49,8 +51,10 @@ POST /projects/:id/merge_requests/:merge_request_iid/context_commits
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `merge_request_iid` (required) - The internal ID of the merge request
+| Attribute           | Type    | Required | Description                                                                                                     |
+|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`                | integer | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `merge_request_iid` | integer | yes      | The internal ID of the merge request                                                                            |
 
 ```plaintext
 POST /projects/:id/merge_requests/
@@ -88,9 +92,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid/context_commits
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `merge_request_iid` (required) - The internal ID of the merge request
-
-| Attribute                  | Type    | Required | Description                                                                     |
-| ---------                  | ----    | -------- | -----------                                                                     |
-| `commits`             | string array | yes | The context commits' SHA  |
+| Attribute           | Type         | Required | Description                                                                                                     |
+|---------------------|--------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`                | integer      | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `merge_request_iid` | integer      | yes      | The internal ID of the merge request                                                                            |
+| `commits`           | string array | yes      | The context commits' SHA                                                                                        |

doc/api/merge_requests.md

@@ -85,7 +85,7 @@ Parameters:
 | `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. |
+| `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. |
 | `with_labels_details`           | boolean        | no       | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
 | `with_merge_status_recheck`     | boolean        | no       | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
 | `created_after`                 | datetime       | no       | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
@@ -272,7 +272,7 @@ Parameters:
 | `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. |
+| `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. |
 | `with_labels_details`           | boolean        | no       | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
 | `with_merge_status_recheck`     | boolean        | no       | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
 | `created_after`                 | datetime       | no       | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
@@ -459,7 +459,7 @@ Parameters:
 | `sort`                          | string         | no       | Return merge 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. |
+| `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. |
 | `with_labels_details`           | boolean        | no       | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.|
 | `with_merge_status_recheck`     | boolean        | no       | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. |
 | `created_after`                 | datetime       | no       | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |

doc/api/milestones.md

@@ -27,7 +27,7 @@ Parameters:
 
 | Attribute                         | Type   | Required | Description |
 | ----------------------------      | ------ | -------- | ----------- |
-| `id`                              | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`                              | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `iids[]`                          | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) |
 | `state`                           | string | optional | Return only `active` or `closed` milestones |
 | `title`                           | string | optional | Return only the milestones having the given `title` |
@@ -68,8 +68,10 @@ GET /projects/:id/milestones/:milestone_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of the project's milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
 
 ## Create new milestone
 
@@ -81,11 +83,13 @@ POST /projects/:id/milestones
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `title` (required) - The title of a milestone
-- `description` (optional) - The description of the milestone
-- `due_date` (optional) - The due date of the milestone
-- `start_date` (optional) - The start date of the milestone
+| Attribute     | Type           | Required | Description                                                                                                     |
+|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`          | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `title`       | string         | yes      | The title of a milestone                                                                                        |
+| `description` | string         | no       | The description of the milestone                                                                                |
+| `due_date`    | string         | no       | The due date of the milestone                                                                                   |
+| `start_date`  | string         | no       | The start date of the milestone                                                                                 |
 
 ## Edit milestone
 
@@ -97,13 +101,15 @@ PUT /projects/:id/milestones/:milestone_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of a project milestone
-- `title` (optional) - The title of a milestone
-- `description` (optional) - The description of a milestone
-- `due_date` (optional) - The due date of the milestone
-- `start_date` (optional) - The start date of the milestone
-- `state_event` (optional) - The state event of the milestone (close or activate)
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
+| `title`        | string         | no       | The title of a milestone                                                                                        |
+| `description`  | string         | no       | The description of the milestone                                                                                |
+| `due_date`     | string         | no       | The due date of the milestone                                                                                   |
+| `start_date`   | string         | no       | The start date of the milestone                                                                                 |
+| `state_event`  | string         | no       | The state event of the milestone (close or activate)                                                            |
 
 ## Delete project milestone
 
@@ -115,8 +121,10 @@ DELETE /projects/:id/milestones/:milestone_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of the project's milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
 
 ## Get all issues assigned to a single milestone
 
@@ -128,8 +136,10 @@ GET /projects/:id/milestones/:milestone_id/issues
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of a project milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
 
 ## Get all merge requests assigned to a single milestone
 
@@ -141,8 +151,10 @@ GET /projects/:id/milestones/:milestone_id/merge_requests
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of a project milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
 
 ## Promote project milestone to a group milestone
 
@@ -156,8 +168,10 @@ POST /projects/:id/milestones/:milestone_id/promote
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of a project milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |
 
 ## Get all burndown chart events for a single milestone **(PREMIUM)**
 
@@ -172,5 +186,7 @@ GET /projects/:id/milestones/:milestone_id/burndown_events
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `milestone_id` (required) - The ID of a project milestone
+| Attribute      | Type           | Required | Description                                                                                                     |
+|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `milestone_id` | integer        | yes      | The ID of the project's milestone                                                                               |

doc/api/notes.md

@@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at
 
 | Attribute           | Type             | Required   | Description                                                                                                                                         |
 | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
 | `issue_iid`         | integer          | yes        | The IID of an issue
 | `sort`              | string           | no         | Return issue notes sorted in `asc` or `desc` order. Default is `desc`
 | `order_by`          | string           | no         | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
@@ -120,9 +120,11 @@ GET /projects/:id/issues/:issue_iid/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `issue_iid` (required) - The IID of a project issue
-- `note_id` (required) - The ID of an issue note
+| Attribute   | Type           | Required | Description                                                                     |
+|-------------|----------------|----------|---------------------------------------------------------------------------------|
+| `id`        | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `issue_iid` | integer        | yes      | The IID of a project issue                                                      |
+| `note_id`   | integer        | yes      | The ID of an issue note                                                         |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
@@ -138,11 +140,13 @@ POST /projects/:id/issues/:issue_iid/notes
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `issue_iid` (required) - The IID of an issue
-- `body` (required) - The content of a note. Limited to 1,000,000 characters.
-- `confidential` (optional) - The confidential flag of a note. Default is false.
-- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
+| Attribute      | Type           | Required | Description                                                                                                                  |
+|----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding).                                             |
+| `issue_iid`    | integer        | yes      | The IID of an issue.                                                                                                       |
+| `body`         | string         | yes      | The content of a note. Limited to 1,000,000 characters.                                                                      |
+| `confidential` | boolean        | no       | The confidential flag of a note. Default is false.                                                                           |
+| `created_at`   | string         | no       | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
@@ -158,11 +162,13 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding).
-- `issue_iid` (required) - The IID of an issue.
-- `note_id` (required) - The ID of a note.
-- `body` (optional) - The content of a note. Limited to 1,000,000 characters.
-- `confidential` (optional) - The confidential flag of a note.
+| Attribute      | Type           | Required | Description                                                                      |
+|----------------|----------------|----------|----------------------------------------------------------------------------------|
+| `id`           | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). |
+| `issue_iid`    | integer        | yes      | The IID of an issue.                                                             |
+| `note_id`      | integer        | yes      | The ID of a note.                                                                |
+| `body`         | string         | no       | The content of a note. Limited to 1,000,000 characters.                          |
+| `confidential` | boolean        | no       | The confidential flag of a note.                                                 |
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
@@ -180,7 +186,7 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `issue_iid` | integer | yes | The IID of an issue |
 | `note_id` | integer | yes | The ID of a note |
 
@@ -203,7 +209,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
 
 | Attribute           | Type             | Required   | Description                                                                                                                                         |
 | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
 | `snippet_id`        | integer          | yes        | The ID of a project snippet
 | `sort`              | string           | no         | Return snippet notes sorted in `asc` or `desc` order. Default is `desc`
 | `order_by`          | string           | no         | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
@@ -222,9 +228,11 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `snippet_id` (required) - The ID of a project snippet
-- `note_id` (required) - The ID of a snippet note
+| Attribute    | Type           | Required | Description                                                                     |
+|--------------|----------------|----------|---------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `snippet_id` | integer        | yes      | The ID of a project snippet                                                     |
+| `note_id`    | integer        | yes      | The ID of a snippet note                                                        |
 
 ```json
 {
@@ -260,10 +268,12 @@ POST /projects/:id/snippets/:snippet_id/notes
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `snippet_id` (required) - The ID of a snippet
-- `body` (required) - The content of a note. Limited to 1,000,000 characters.
-- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
+| Attribute    | Type           | Required | Description                                                                                                                  |
+|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)                                              |
+| `snippet_id` | integer        | yes      | The ID of a snippet                                                                                                          |
+| `body`       | string         | yes      | The content of a note. Limited to 1,000,000 characters.                                                                      |
+| `created_at` | string         | no       | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"
@@ -279,10 +289,12 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `snippet_id` (required) - The ID of a snippet
-- `note_id` (required) - The ID of a note
-- `body` (required) - The content of a note. Limited to 1,000,000 characters.
+| Attribute    | Type           | Required | Description                                                                                                                  |
+|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)                                              |
+| `snippet_id` | integer        | yes      | The ID of a snippet                                                                                                          |
+| `note_id`    | integer        | yes      | The ID of a snippet note                                                        |
+| `body`       | string         | yes      | The content of a note. Limited to 1,000,000 characters.                                                                      |
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note"
@@ -300,7 +312,7 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `snippet_id` | integer | yes | The ID of a snippet |
 | `note_id` | integer | yes | The ID of a note |
 
@@ -321,7 +333,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda
 
 | Attribute           | Type             | Required   | Description                                                                                                                                         |
 | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
 | `merge_request_iid` | integer          | yes        | The IID of a project merge request
 | `sort`              | string           | no         | Return merge request notes sorted in `asc` or `desc` order. Default is `desc`
 | `order_by`          | string           | no         | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
@@ -340,9 +352,11 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `merge_request_iid` (required) - The IID of a project merge request
-- `note_id` (required) - The ID of a merge request note
+| Attribute           | Type           | Required | Description                                                                     |
+|---------------------|----------------|----------|---------------------------------------------------------------------------------|
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `merge_request_iid` | integer        | yes      | The IID of a project merge request                                              |
+| `note_id`           | integer        | yes      | The ID of a merge request note                                                        |
 
 ```json
 {
@@ -383,10 +397,12 @@ POST /projects/:id/merge_requests/:merge_request_iid/notes
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `merge_request_iid` (required) - The IID of a merge request
-- `body` (required) - The content of a note. Limited to 1,000,000 characters.
-- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
+| Attribute           | Type           | Required | Description                                                                                                                  |
+|---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)                                              |
+| `merge_request_iid` | integer        | yes      | The IID of a project merge request                                                                                           |
+| `body`              | string         | yes      | The content of a note. Limited to 1,000,000 characters.                                                                      |
+| `created_at`        | string         | no       | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
 
 ### Modify existing merge request note
 
@@ -398,10 +414,12 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
-- `merge_request_iid` (required) - The IID of a merge request
-- `note_id` (required) - The ID of a note
-- `body` (required) - The content of a note. Limited to 1,000,000 characters.
+| Attribute           | Type           | Required | Description                                                                     |
+|---------------------|----------------|----------|---------------------------------------------------------------------------------|
+| `id`                | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `merge_request_iid` | integer        | yes      | The IID of a project merge request                                              |
+| `note_id`           | integer        | no       | The ID of a note                                                                |
+| `body`              | string         | yes      | The content of a note. Limited to 1,000,000 characters.                         |
 
 ```shell
 curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"
@@ -419,7 +437,7 @@ Parameters:
 
 | Attribute | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `merge_request_iid` | integer | yes | The IID of a merge request |
 | `note_id` | integer | yes | The ID of a note |
 
@@ -440,7 +458,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
 
 | Attribute           | Type             | Required   | Description |
 | ------------------- | ---------------- | ---------- | ----------- |
-| `id`                | integer/string   | yes        | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
+| `id`                | integer or string   | yes        | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
 | `epic_id`           | integer          | yes        | The ID of a group epic |
 | `sort`              | string           | no         | Return epic notes sorted in `asc` or `desc` order. Default is `desc` |
 | `order_by`          | string           | no         | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` |
@@ -461,7 +479,7 @@ Parameters:
 
 | Attribute | Type           | Required | Description |
 | --------- | -------------- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
 | `epic_id` | integer | yes  | The ID of an epic |
 | `note_id` | integer | yes  | The ID of a note |
 
@@ -502,7 +520,7 @@ Parameters:
 
 | Attribute | Type           | Required | Description |
 | --------- | -------------- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
 | `epic_id` | integer | yes  | The ID of an epic |
 | `body`    | string  | yes  | The content of a note. Limited to 1,000,000 characters. |
 
@@ -522,7 +540,7 @@ Parameters:
 
 | Attribute | Type           | Required | Description |
 | --------- | -------------- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
 | `epic_id` | integer | yes  | The ID of an epic |
 | `note_id` | integer | yes  | The ID of a note |
 | `body`    | string  | yes  | The content of a note. Limited to 1,000,000 characters. |
@@ -543,7 +561,7 @@ Parameters:
 
 | Attribute | Type           | Required | Description |
 | --------- | -------------- | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
 | `epic_id` | integer | yes  | The ID of an epic |
 | `note_id` | integer | yes  | The ID of a note |
 

doc/api/oauth2.md

@@ -98,7 +98,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
    This page asks the user to approve the request from the app to access their
    account based on the scopes specified in `REQUESTED_SCOPES`. The user is then
    redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
-   is a space separated list of scopes associated with the user.
+   is a space-separated list of scopes associated with the user.
    For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes.
    The redirect includes the authorization `code`, for example:
 
@@ -126,7 +126,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
     "created_at": 1607635748
    }
    ```
-  
+
 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
    be used even after the `access_token` itself expires. This request:
    - Invalidates the existing `access_token` and `refresh_token`.
@@ -178,7 +178,7 @@ be used as a CSRF token.
    This page asks the user to approve the request from the app to access their
    account based on the scopes specified in `REQUESTED_SCOPES`. The user is then
    redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
-   is a space separated list of scopes associated with the user.
+   is a space-separated list of scopes associated with the user.
    For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes.
    The redirect includes the authorization `code`, for example:
 
@@ -206,7 +206,7 @@ be used as a CSRF token.
     "created_at": 1607635748
    }
    ```
-  
+
 1. To retrieve a new `access_token`, use the `refresh_token` parameter. Refresh tokens may
    be used even after the `access_token` itself expires. This request:
    - Invalidates the existing `access_token` and `refresh_token`.
@@ -266,7 +266,7 @@ https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIREC
 This prompts the user to approve the applications access to their account
 based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
 the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
-   is a space separated list of scopes you want to have access to (for example, `scope=read_user+profile`
+   is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile`
 would request `read_user` and `profile` scopes). The redirect
 includes a fragment with `access_token` as well as token details in GET
 parameters, for example:

doc/api/project_badges.md

@@ -11,7 +11,7 @@ type: reference, api
 
 ## Placeholder tokens
 
-Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are:
+Badges support placeholders that are replaced in real-time in both the link and image URL. The allowed placeholders are:
 
 <!-- vale gitlab.Spelling = NO -->
 

doc/api/project_clusters.md

@@ -384,7 +384,6 @@ Example response:
     }
   }
 }
-
 ```
 
 ## Delete project cluster

doc/api/project_snippets.md

@@ -36,7 +36,9 @@ GET /projects/:id/snippets
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
+| Attribute | Type           | Required | Description                                                                                                     |
+|-----------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 
 ## Single snippet
 
@@ -48,8 +50,10 @@ GET /projects/:id/snippets/:snippet_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `snippet_id` (required) - The ID of a project's snippet
+| Attribute    | Type           | Required | Description                                                                                                     |
+|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `snippet_id` | integer        | yes      | The ID of a project's snippet                                                                                   |
 
 ```json
 {
@@ -85,7 +89,7 @@ Parameters:
 
 | Attribute         | Type            | Required | Description                                                                                                     |
 |:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------|
-| `id`              | integer         | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`              | integer or string         | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `title`           | string          | yes      | Title of a snippet                                                                                              |
 | `file_name`       | string          | no       | Deprecated: Use `files` instead. Name of a snippet file                                                         |
 | `content`         | string          | no       | Deprecated: Use `files` instead. Content of a snippet                                                           |
@@ -132,7 +136,7 @@ Parameters:
 
 | Attribute             | Type            | Required | Description                                                                                                     |
 |:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------|
-| `id`                  | integer         | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `id`                  | integer or string         | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
 | `snippet_id`          | integer         | yes      | The ID of a project's snippet                                                                                   |
 | `title`               | string          | no       | Title of a snippet                                                                                              |
 | `file_name`           | string          | no       | Deprecated: Use `files` instead. Name of a snippet file                                                         |
@@ -183,8 +187,10 @@ DELETE /projects/:id/snippets/:snippet_id
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `snippet_id` (required) - The ID of a project's snippet
+| Attribute    | Type           | Required | Description                                                                                                     |
+|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `snippet_id` | integer        | yes      | The ID of a project's snippet                                                                                   |
 
 Example request:
 
@@ -203,8 +209,10 @@ GET /projects/:id/snippets/:snippet_id/raw
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `snippet_id` (required) - The ID of a project's snippet
+| Attribute    | Type           | Required | Description                                                                                                     |
+|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `snippet_id` | integer        | yes      | The ID of a project's snippet                                                                                   |
 
 Example request:
 
@@ -223,10 +231,12 @@ GET /projects/:id/snippets/:snippet_id/files/:ref/:file_path/raw
 
 Parameters:
 
-- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
-- `snippet_id` (required) - The ID of a project's snippet
-- `ref` (required) - The name of a branch, tag or commit, such as `main`
-- `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb`
+| Attribute    | Type           | Required | Description                                                                                                     |
+|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `snippet_id` | integer        | yes      | The ID of a project's snippet                                                                                   |
+| `ref`        | string         | yes      | The name of a branch, tag or commit e.g. master                                                                 |
+| `file_path`  | string         | yes      | The URL-encoded path to the file, e.g. snippet%2Erb                                                             |
 
 Example request:
 
@@ -245,10 +255,10 @@ Available only for users with the Administrator [role](../user/permissions.md).
 GET /projects/:id/snippets/:snippet_id/user_agent_detail
 ```
 
-| Attribute     | Type    | Required | Description                          |
-|---------------|---------|----------|--------------------------------------|
-| `id`          | integer or string | yes      | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). |
-| `snippet_id`  | Integer | yes      | The ID of a snippet                  |
+| Attribute    | Type           | Required | Description                                                                                                     |
+|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`         | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
+| `snippet_id` | Integer        | yes      | The ID of a snippet                                                                                             |
 
 Example request:
 

doc/api/project_statistics.md

@@ -21,7 +21,7 @@ GET /projects/:id/statistics
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 
 Example response:
 

doc/api/project_templates.md

@@ -33,7 +33,7 @@ GET /projects/:id/templates/:type
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `type`     | string | yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, `merge_requests` |
 
 Example response (licenses):
@@ -99,7 +99,7 @@ GET /projects/:id/templates/:type/:name
 
 | Attribute  | Type   | Required | Description |
 | ---------- | ------ | -------- | ----------- |
-| `id`      | integer / string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `type`     | string | yes| The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. |
 | `name`     | string | yes      | The key of the template, as obtained from the collection endpoint |
 | `source_template_project_id`   | integer | no      | The project ID where a given template is being stored. This is useful when multiple templates from different projects have the same name. If multiple templates have the same name, the match from `closest ancestor` is returned if `source_template_project_id` is not specified |

doc/api/projects.md

@@ -2488,8 +2488,8 @@ GET /projects/:id/push_rule
 {
   "id": 1,
   "project_id": 3,
-  "commit_message_regex": "Fixes \d+\..*",
-  "commit_message_negative_regex": "ssh\:\/\/",
+  "commit_message_regex": "Fixes \\d+\\..*",
+  "commit_message_negative_regex": "ssh\\:\\/\\/",
   "branch_name_regex": "",
   "deny_delete_tag": false,
   "created_at": "2012-10-12T17:04:47Z",

doc/api/protected_environments.md

@@ -117,13 +117,13 @@ Example response:
 
 ```json
 {
-   "name":"production",
-   "deploy_access_levels":[
+   "name": "production",
+   "deploy_access_levels": [
       {
-         "access_level":40,
-         "access_level_description":"protected-access-group",
-         "user_id":null,
-         "group_id":9899826
+         "access_level": 40,
+         "access_level_description": "protected-access-group",
+         "user_id": null,
+         "group_id": 9899826
       }
    ]
 }

doc/api/repositories.md

@@ -28,7 +28,7 @@ Supported attributes:
 
 | Attribute   | Type           | Required | Description |
 | :---------- | :------------- | :------- | :---------- |
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`        | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `path`      | string         | no       | The path inside repository. Used to get content of subdirectories. |
 | `ref`       | string         | no       | The name of a repository branch or tag or if not given the default branch. |
 | `recursive` | boolean        | no       | Boolean value used to get a recursive tree (false by default). |
@@ -104,7 +104,7 @@ Supported attributes:
 
 | Attribute | Type           | Required | Description |
 | :-------- | :------------- | :------- | :---------- |
-| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `sha`     | string         | yes      | The blob SHA. |
 
 ## Raw blob content
@@ -146,7 +146,7 @@ Supported attributes:
 
 | Attribute   | Type           | Required | Description           |
 |:------------|:---------------|:---------|:----------------------|
-| `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`        | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `sha`       | string         | no       | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. |
 | `path`      | string         | no       | The subpath of the repository to download. This defaults to the whole repository (empty string).  |
 
@@ -169,7 +169,7 @@ Supported attributes:
 
 | Attribute         | Type           | Required | Description |
 | :---------        | :------------- | :------- | :---------- |
-| `id`              | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`              | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `from`            | string         | yes      | The commit SHA or branch name. |
 | `to`              | string         | yes      | The commit SHA or branch name. |
 | `from_project_id` | integer        | no       | The ID to compare from |
@@ -231,7 +231,7 @@ Supported attributes:
 
 | Attribute  | Type           | Required | Description |
 | :--------- | :------------- | :------- | :---------- |
-| `id`       | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `id`       | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
 | `order_by` | string         | no       | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. |
 | `sort`     | string         | no       | Return contributors sorted in `asc` or `desc` order. Default is `asc`. |
 
@@ -263,7 +263,7 @@ GET /projects/:id/repository/merge_base
 
 | Attribute | Type           | Required | Description |
 | --------- | -------------- | -------- | ------------------------------------------------------------------------------- |
-| `id`      | integer/string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
+| `id`      | integer or string | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
 | `refs`    | array          | yes      | The refs to find the common ancestor of, multiple refs can be passed            |
 
 Example request:

doc/api/repository_files.md

@@ -35,6 +35,12 @@ GET /projects/:id/repository/files/:file_path
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"
 ```
 
+| Attribute   | Type           | Required | Description                                                                                                     |
+|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`        | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path` | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `ref`       | string         | yes      | The name of branch, tag or commit                                                                               |
+
 Example response:
 
 ```json
@@ -52,11 +58,6 @@ Example response:
 }
 ```
 
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
-- `ref` (required) - The name of branch, tag or commit
-
 NOTE:
 `blob_id` is the blob SHA, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository)
 
@@ -95,6 +96,12 @@ Allows you to receive blame information. Each blame range contains lines and cor
 GET /projects/:id/repository/files/:file_path/blame
 ```
 
+| Attribute   | Type           | Required | Description                                                                                                     |
+|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`        | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path` | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `ref`       | string         | yes      | The name of branch, tag or commit                                                                               |
+
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"
 ```
@@ -127,11 +134,6 @@ Example response:
 ]
 ```
 
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
-- `ref` (required) - The name of branch, tag or commit
-
 NOTE:
 `HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository).
 
@@ -162,15 +164,16 @@ X-Gitlab-Size: 1476
 GET /projects/:id/repository/files/:file_path/raw
 ```
 
+| Attribute   | Type           | Required | Description                                                                                                     |
+|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`        | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path` | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `ref`       | string         | yes      | The name of branch, tag or commit. Default is the `HEAD` of the project.                                        |
+
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master"
 ```
 
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file, such as lib%2Fclass%2Erb.
-- `ref` (optional) - The name of branch, tag or commit. Default is the `HEAD` of the project.
-
 NOTE:
 Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata.
 
@@ -182,6 +185,18 @@ This allows you to create a single file. For creating multiple files with a sing
 POST /projects/:id/repository/files/:file_path
 ```
 
+| Attribute        | Type           | Required | Description                                                                                                     |
+|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`             | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path`      | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `branch`         | string         | yes      | Name of the branch                                                                                              |
+| `start_branch`   | string         | no       | Name of the branch to start the new commit from                                                                 |
+| `encoding`       | string         | no       | Change encoding to `base64`. Default is `text`.                                                                 |
+| `author_email`   | string         | no       | Specify the commit author's email address                                                                       |
+| `author_name`    | string         | no       | Specify the commit author's name                                                                                |
+| `content`        | string         | yes      | File content                                                                                                    |
+| `commit_message` | string         | yes      | Commit message                                                                                                  |
+
 ```shell
 curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \
      --header "Content-Type: application/json" \
@@ -199,17 +214,6 @@ Example response:
 }
 ```
 
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
-- `branch` (required) - Name of the branch
-- `start_branch` (optional) - Name of the branch to start the new commit from
-- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
-- `author_email` (optional) - Specify the commit author's email address
-- `author_name` (optional) - Specify the commit author's name
-- `content` (required) - File content
-- `commit_message` (required) - Commit message
-
 ## Update existing file in repository
 
 This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
@@ -218,6 +222,19 @@ This allows you to update a single file. For updating multiple files with a sing
 PUT /projects/:id/repository/files/:file_path
 ```
 
+| Attribute        | Type           | Required | Description                                                                                                     |
+|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`             | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path`      | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `branch`         | string         | yes      | Name of the branch                                                                                              |
+| `start_branch`   | string         | no       | Name of the branch to start the new commit from                                                                 |
+| `encoding`       | string         | no       | Change encoding to `base64`. Default is `text`.                                                                 |
+| `author_email`   | string         | no       | Specify the commit author's email address                                                                       |
+| `author_name`    | string         | no       | Specify the commit author's name                                                                                |
+| `content`        | string         | yes      | File content                                                                                                    |
+| `commit_message` | string         | yes      | Commit message                                                                                                  |
+| `last_commit_id` | string         | no       | Last known file commit ID                                                                                       |
+
 ```shell
 curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \
      --header "Content-Type: application/json" \
@@ -235,18 +252,6 @@ Example response:
 }
 ```
 
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
-- `branch` (required) - Name of the branch
-- `start_branch` (optional) - Name of the branch to start the new commit from
-- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
-- `author_email` (optional) - Specify the commit author's email address
-- `author_name` (optional) - Specify the commit author's name
-- `content` (required) - New file content
-- `commit_message` (required) - Commit message
-- `last_commit_id` (optional) - Last known file commit ID
-
 If the commit fails for any reason we return a 400 error with a non-specific
 error message. Possible causes for a failed commit include:
 
@@ -265,6 +270,17 @@ This allows you to delete a single file. For deleting multiple files with a sing
 DELETE /projects/:id/repository/files/:file_path
 ```
 
+| Attribute        | Type           | Required | Description                                                                                                     |
+|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
+| `id`             | integer or string | yes   | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user  |
+| `file_path`      | string         | yes      | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`.                                                      |
+| `branch`         | string         | yes      | Name of the branch                                                                                              |
+| `start_branch`   | string         | no       | Name of the branch to start the new commit from                                                                 |
+| `author_email`   | string         | no       | Specify the commit author's email address.                                                                      |
+| `author_name`    | string         | no       | Specify the commit author's name.                                                                               |
+| `commit_message` | string         | yes      | Commit message.                                                                                                 |
+| `last_commit_id` | string         | no       | Last known file commit ID.                                                                                      |
+
 ```shell
 curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
      --header "Content-Type: application/json" \
@@ -272,13 +288,3 @@ curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
        "commit_message": "delete file"}' \
      "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
 ```
-
-Parameters:
-
-- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
-- `branch` (required) - Name of the branch
-- `start_branch` (optional) - Name of the branch to start the new commit from
-- `author_email` (optional) - Specify the commit author's email address
-- `author_name` (optional) - Specify the commit author's name
-- `commit_message` (required) - Commit message
-- `last_commit_id` (optional) - Last known file commit ID

doc/api/users.md

@@ -269,7 +269,9 @@ GET /users/:id
 
 Parameters:
 
-- `id` (required) - The ID of a user
+| Attribute | Type    | Required | Description      |
+|-----------|---------|----------|------------------|
+| `id`      | integer | yes      | The ID of a user |
 
 ```json
 {
@@ -303,7 +305,9 @@ GET /users/:id
 
 Parameters:
 
-- `id` (required) - The ID of a user
+| Attribute | Type    | Required | Description      |
+|-----------|---------|----------|------------------|
+| `id`      | integer | yes      | The ID of a user |
 
 Example Responses:
 
@@ -509,8 +513,10 @@ DELETE /users/:id/identities/:provider
 
 Parameters:
 
-- `id` (required) - The ID of the user
-- `provider` (required) - External provider name
+| Attribute  | Type    | Required | Description            |
+|------------|---------|----------|------------------------|
+| `id`       | integer | yes      | The ID of a user       |
+| `provider` | string  | yes      | External provider name |
 
 ## User deletion
 
@@ -523,10 +529,10 @@ DELETE /users/:id
 
 Parameters:
 
-- `id` (required) - The ID of the user
-- `hard_delete` (optional) - If true, contributions that would usually be
-  [moved to the ghost user](../user/profile/account/delete_account.md#associated-records)
-  are deleted instead, as well as groups owned solely by this user.
+| Attribute     | Type    | Required | Description                                  |
+|---------------|---------|----------|----------------------------------------------|
+| `id`          | integer | yes      | The ID of a user                             |
+| `hard_delete` | boolean | no       | If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. |
 
 ## List current user (for normal users)
 
@@ -576,14 +582,16 @@ GET /user
 
 ## List current user (for admins)
 
-Parameters:
-
-- `sudo` (optional) - the ID of a user to make the call in their place
-
 ```plaintext
 GET /user
 ```
 
+Parameters:
+
+| Attribute | Type    | Required | Description                                      |
+|-----------|---------|----------|--------------------------------------------------|
+| `sudo`    | integer | no       | the ID of a user to make the call in their place |
+
 ```json
 {
   "id": 1,
@@ -936,7 +944,9 @@ GET /user/keys/:key_id
 
 Parameters:
 
-- `key_id` (required) - The ID of an SSH key
+| Attribute | Type   | Required | Description          |
+|-----------|--------|----------|----------------------|
+| `key_id`  | string | yes      | The ID of an SSH key |
 
 ```json
 {
@@ -957,9 +967,11 @@ POST /user/keys
 
 Parameters:
 
-- `title` (required) - new SSH key's title
-- `key` (required) - new SSH key
-- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
+| Attribute    | Type   | Required | Description                                                                    |
+|--------------|--------|----------|--------------------------------------------------------------------------------|
+| `title`      | string | yes      | new SSH key's title                                                            |
+| `key`        | string | yes      | new SSH key                                                                    |
+| `expires_at` | string | no       | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
 
 ```json
 {
@@ -995,10 +1007,12 @@ POST /users/:id/keys
 
 Parameters:
 
-- `id` (required) - ID of specified user
-- `title` (required) - new SSH key's title
-- `key` (required) - new SSH key
-- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
+| Attribute    | Type    | Required | Description                                                                    |
+|--------------|---------|----------|--------------------------------------------------------------------------------|
+| `id`         | integer | yes      | ID of specified user                                                           |
+| `title`      | string  | yes      | new SSH key's title                                                            |
+| `key`        | string  | yes      | new SSH key                                                                    |
+| `expires_at` | string  | no       | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
 
 NOTE:
 This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)**
@@ -1014,7 +1028,9 @@ DELETE /user/keys/:key_id
 
 Parameters:
 
-- `key_id` (required) - SSH key ID
+| Attribute | Type    | Required | Description |
+|-----------|---------|----------|-------------|
+| `key_id`  | integer | yes      | SSH key ID  |
 
 ## Delete SSH key for given user
 
@@ -1026,8 +1042,10 @@ DELETE /users/:id/keys/:key_id
 
 Parameters:
 
-- `id` (required) - ID of specified user
-- `key_id` (required) - SSH key ID
+| Attribute | Type    | Required | Description          |
+|-----------|---------|----------|----------------------|
+| `id`      | integer | yes      | ID of specified user |
+| `key_id`  | integer | yes      | SSH key ID           |
 
 ## List all GPG keys
 
@@ -1092,8 +1110,8 @@ POST /user/gpg_keys
 Parameters:
 
 | Attribute | Type   | Required | Description     |
-| --------- | ------ | -------- | --------------- |
-| key       | string | yes      | The new GPG key |
+|-----------|--------|----------|-----------------|
+| `key`     | string | yes      | The new GPG key |
 
 ```shell
 curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
@@ -1288,7 +1306,9 @@ GET /users/:id/emails
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute | Type    | Required | Description          |
+|-----------|---------|----------|----------------------|
+| `id`      | integer | yes      | ID of specified user |
 
 ## Single email
 
@@ -1300,7 +1320,9 @@ GET /user/emails/:email_id
 
 Parameters:
 
-- `email_id` (required) - email ID
+| Attribute  | Type    | Required | Description |
+|------------|---------|----------|-------------|
+| `email_id` | integer | yes      | Email ID    |
 
 ```json
 {
@@ -1320,7 +1342,9 @@ POST /user/emails
 
 Parameters:
 
-- `email` (required) - email address
+| Attribute | Type   | Required | Description |
+|-----------|--------|----------|-------------|
+| `email`   | string | yes      | Email address |
 
 ```json
 {
@@ -1353,9 +1377,11 @@ POST /users/:id/emails
 
 Parameters:
 
-- `id` (required) - ID of specified user
-- `email` (required) - email address
-- `skip_confirmation` (optional) - Skip confirmation and assume email is verified - true or false (default)
+| Attribute           | Type    | Required | Description                                                               |
+|---------------------|---------|----------|---------------------------------------------------------------------------|
+| `id`                | string  | yes      | ID of specified user                                                      |
+| `email`             | string  | yes      | Email address                                                             |
+| `skip_confirmation` | boolean | no       | Skip confirmation and assume email is verified - true or false (default) |
 
 ## Delete email for current user
 
@@ -1368,7 +1394,9 @@ DELETE /user/emails/:email_id
 
 Parameters:
 
-- `email_id` (required) - email ID
+| Attribute  | Type    | Required | Description |
+|------------|---------|----------|-------------|
+| `email_id` | integer | yes      | Email ID    |
 
 ## Delete email for given user
 
@@ -1380,8 +1408,10 @@ DELETE /users/:id/emails/:email_id
 
 Parameters:
 
-- `id` (required) - ID of specified user
-- `email_id` (required) - email ID
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
+| `email_id` | integer | yes      | Email ID             |
 
 ## Block user
 
@@ -1393,7 +1423,9 @@ POST /users/:id/block
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
 
 Returns:
 
@@ -1413,7 +1445,9 @@ POST /users/:id/unblock
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
 
 Returns `201 OK` on success, `404 User Not Found` is user cannot be found or
 `403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
@@ -1430,7 +1464,9 @@ POST /users/:id/deactivate
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
 
 Returns:
 
@@ -1453,7 +1489,9 @@ POST /users/:id/activate
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
 
 Returns:
 
@@ -1572,7 +1610,9 @@ POST /users/:id/approve
 
 Parameters:
 
-- `id` (required) - ID of specified user
+| Attribute  | Type    | Required | Description          |
+|------------|---------|----------|----------------------|
+| `id`       | integer | yes      | ID of specified user |
 
 ```shell
 curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve"
@@ -1731,10 +1771,6 @@ It revokes an impersonation token.
 DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
 ```
 
-```shell
-curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
-```
-
 Parameters:
 
 | Attribute                | Type    | Required | Description                       |
@@ -1742,6 +1778,10 @@ Parameters:
 | `user_id`                | integer | yes      | The ID of the user                |
 | `impersonation_token_id` | integer | yes      | The ID of the impersonation token |
 
+```shell
+curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
+```
+
 ## Create a personal access token **(FREE SELF)**
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6.