api-ref: Document domain specific roles

Add domain_id parameter to the /roles API documentation,
and example request and response json's.

Change-Id: I213883b8402b518e041542ae1c3c169612a096c5
Closes-Bug: #1609171

api-ref/source/v3/parameters.yaml

@@ -630,12 +630,6 @@ domain_group_identity:
   in: body
   required: true
   type: object
-domain_id_response_body:
-  description: |
-    The ID of the domain for the user.
-  in: body
-  required: true
-  type: string
 domain_id_response_body:
   description: |
     The ID of the domain.

api-ref/source/v3/roles.inc

@@ -394,6 +394,7 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - name: role_name_query
+   - domain_id: domain_id_query
 
 Response Parameters
 -------------------
@@ -402,6 +403,7 @@ Response Parameters
 
    - links: link_collection
    - roles: roles
+   - domain_id: domain_id_response_body
    - id: role_id_response_body
    - links: link_response_body
    - name: role_name_response_body
@@ -432,6 +434,7 @@ Request
 
    - role: role
    - name: role_name_create_body
+   - domain_id: domain_id_response_body
 
 Request Example
 ---------------
@@ -439,12 +442,19 @@ Request Example
 .. literalinclude:: ./samples/admin/role-create-request.json
    :language: javascript
 
+Request Example for Domain Specific Role
+----------------------------------------
+
+.. literalinclude:: ./samples/admin/domain-specific-role-create-request.json
+   :language: javascript
+
 Response Parameters
 -------------------
 
 .. rest_parameters:: parameters.yaml
 
    - role: role
+   - domain_id: domain_id_response_body
    - id: role_id_response_body
    - links: link_response_body
    - name: role_name_response_body
@@ -581,6 +591,7 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - role: role
+   - domain_id: domain_id_response_body
    - id: role_id_response_body
    - links: link_response_body
    - name: role_name_response_body
@@ -625,6 +636,7 @@ Response Parameters
 .. rest_parameters:: parameters.yaml
 
    - role: role
+   - domain_id: domain_id_response_body
    - id: role_id_response_body
    - links: link_response_body
    - name: role_name_response_body

api-ref/source/v3/samples/admin/domain-specific-role-create-request.json

@@ -0,0 +1,6 @@
+{
+    "role": {
+        "domain_id": "92e782c4988642d783a95f4a87c3fdd7",
+        "name": "developer"
+    }
+}

api-ref/source/v3/samples/admin/role-show-response.json

@@ -1,5 +1,6 @@
 {
     "role": {
+        "domain_id": "d07792fd66ac4ed881723ab9f1c9925f",
         "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
         "links": {
             "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"

api-ref/source/v3/samples/admin/role-update-response.json

@@ -1,5 +1,6 @@
 {
     "role": {
+        "domain_id": "73748865fb964ded9e836d491d32dcfb",
         "id": "1e443fa8cee3482a8a2b6954dd5c8f12",
         "links": {
             "self": "http://example.com/identity/v3/roles/1e443fa8cee3482a8a2b6954dd5c8f12"