From 251cf107f2bb82d5737897c3d8e973a6bc4046f2 Mon Sep 17 00:00:00 2001
From: Tin Lam <tinlam@gmail.com>
Date: Tue, 16 Aug 2016 14:45:36 -0500
Subject: [PATCH] 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                    |  6 ------
 api-ref/source/v3/roles.inc                          | 12 ++++++++++++
 .../admin/domain-specific-role-create-request.json   |  6 ++++++
 .../source/v3/samples/admin/role-show-response.json  |  1 +
 .../v3/samples/admin/role-update-response.json       |  1 +
 5 files changed, 20 insertions(+), 6 deletions(-)
 create mode 100644 api-ref/source/v3/samples/admin/domain-specific-role-create-request.json

diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 56f6a87a50..8e0fb17825 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/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.
diff --git a/api-ref/source/v3/roles.inc b/api-ref/source/v3/roles.inc
index 76df971293..48d2979e30 100644
--- a/api-ref/source/v3/roles.inc
+++ b/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
diff --git a/api-ref/source/v3/samples/admin/domain-specific-role-create-request.json b/api-ref/source/v3/samples/admin/domain-specific-role-create-request.json
new file mode 100644
index 0000000000..428022c8a3
--- /dev/null
+++ b/api-ref/source/v3/samples/admin/domain-specific-role-create-request.json
@@ -0,0 +1,6 @@
+{
+    "role": {
+        "domain_id": "92e782c4988642d783a95f4a87c3fdd7",
+        "name": "developer"
+    }
+}
diff --git a/api-ref/source/v3/samples/admin/role-show-response.json b/api-ref/source/v3/samples/admin/role-show-response.json
index 0d24401763..e93de6da11 100644
--- a/api-ref/source/v3/samples/admin/role-show-response.json
+++ b/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"
diff --git a/api-ref/source/v3/samples/admin/role-update-response.json b/api-ref/source/v3/samples/admin/role-update-response.json
index 0d24401763..b9c86efdd2 100644
--- a/api-ref/source/v3/samples/admin/role-update-response.json
+++ b/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"