[DOCS] Formatted roles API (elastic/x-pack-elasticsearch#2577)

* [DOCS] Formatted roles API

* [DOCS] Addressed feedback about roles API

Original commit: elastic/x-pack-elasticsearch@414d06bc13

docs/en/rest-api/security/roles.asciidoc

@@ -3,10 +3,72 @@
 === Role Management APIs
 
 The Roles API enables you to add, remove, and retrieve roles in the `native`
-realm. To use this API, you must have at least the `manage_security` cluster
+realm.
+
+==== Request
+
+`GET /_xpack/security/role` +
+
+`GET /_xpack/security/role/<name>` +
+
+`POST /_xpack/security/role/<name>/_clear_cache` +
+
+`POST /_xpack/security/role/<name>` +
+
+`PUT /_xpack/security/role/<name>`
+
+
+==== Description
+
+The Roles API is generally the preferred way to manage roles, rather than using
+file-based role management. For more information, see
+{xpack-ref}/authorization.html[Configuring Role-based Access Control].
+
+
+==== Path Parameters
+
+`name`::
+  (string) The name of the role. If you do not specify this parameter, the
+  Get Roles API returns information about all roles.
+
+
+==== Request Body
+
+The following parameters can be specified in the body of a PUT or POST request
+and pertain to adding a role:
+
+`cluster`:: (list) A list of cluster privileges. These privileges define the
+cluster level actions that users with this role are able to execute.
+
+`indices`:: (list) A list of indices permissions entries.
+`field_security`::: (list) The document fields that the owners of the role have
+read access to. For more information, see
+{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
+`names` (required)::: (list) A list of indices (or index name patterns) to which the
+permissions in this entry apply.
+`privileges`(required)::: (list) The index level privileges that the owners of the role
+have on the specified indices.
+`query`::: A search query that defines the documents the owners of the role have
+read access to. A document within the specified indices must match this query in
+order for it to be accessible by the owners of the role.
+
+`metadata`:: (object) Optional meta-data. Within the `metadata` object, keys
+that begin with `_` are reserved for system usage.
+
+`run_as`:: (list) A list of users that the owners of this role can impersonate.
+For more information, see
+{xpack-ref}/run-as-privilege.html[Submitting Requests on Behalf of Other Users].
+
+For more information, see {xpack-ref}/defining-roles.html[Defining Roles].
+
+
+==== Authorization
+
+To use this API, you must have at least the `manage_security` cluster
 privilege.
 
-NOTE: The Roles API is now the preferred way to manage roles.
+
+==== Examples
 
 [[security-api-put-role]]
 To add a role, submit a PUT or POST request to the `/_xpack/security/role/<rolename>`
@@ -35,15 +97,6 @@ POST /_xpack/security/role/my_admin_role
 --------------------------------------------------
 // CONSOLE
 
-The `name`, `cluster`, and `indices` fields are required at the top-level.
-Within the `indices` array, the `names` and `privileges` fields are required.
-Within the `metadata` object, keys beginning with `_` are reserved for system
-usage.
-
-The `field_security` and `query` fields are both optional. They are used to
-implement field and document level security. For more information, see
-{xpack-ref}/field-and-document-access-control.html[Setting Up Field and Document Level Security].
-
 A successful call returns a JSON structure that shows whether the role has been
 created or updated.