api-ref update for roles assignments with names

Updates the api-ref to reflect that list_role_assignment now also
return the donain id and name for roles.

Related-Bug: #1607114
Change-Id: Ie887907b9410e84b5f3ff958b05b2fd98efbe5aa

api-ref/source/v3/inherit.inc

@@ -444,7 +444,7 @@ additionally include the names of the entities. For example:
 ``GET /v3/role_assignments?user.id={user_id}&effective&include_names=true``
 would return:
 
-.. literalinclude::samples/admin/role-assignments-effective-list-include-names-response.json
+.. literalinclude:: samples/admin/role-assignments-effective-list-include-names-response.json
    :language: javascript
 
 Normal response codes: 200

api-ref/source/v3/roles.inc

@@ -77,6 +77,15 @@ in the response, the ``links`` entity section for each assignment gained by
 virtue of group membership will contain a URL that enables access to the
 membership of the group.
 
+By default only the IDs of entities are returned in collections from the
+role_assignment API calls. The names of entities may also be returned,
+in addition to the IDs, by using the ``include_names`` query parameter
+on any of these calls, for example:
+
+- List role assignments including names::
+
+    GET /role_assignments?include_names
+
 
 List roles
 ==========

api-ref/source/v3/samples/admin/role-assignments-effective-list-include-names-response.json

@@ -5,6 +5,10 @@
                     "assignment": "http://example.com/identity/v3/domains/161718/users/313233/roles/123456"
                 },
                 "role": {
+                    "domain": {
+                        "id": "161718",
+                        "name": "Default"
+                    },
                     "id": "123456",
                     "name": "admin"
                 },
@@ -29,6 +33,10 @@
                     "membership": "http://example.com/identity/v3/groups/101112/users/313233"
                 },
                 "role": {
+                    "domain": {
+                        "id": "161718",
+                        "name": "Default"
+                    },
                     "id": "123456",
                     "name": "admin"
                 },
@@ -57,4 +65,4 @@
             "previous": null,
             "next": null
         }
-    }
+    }