api-ref: Add query options to GET /projects API documentation

Add the following query options to the api-ref:

* parents_as_list (key-only, no value expected)
* subtree_as_list (key-only, no value expected)
* parents_as_ids (key-only, no value expected)
* subtree_as_ids (key-only, no value expected)

Change-Id: Ie9362885d57112c81c7141c4238e9e3d5d3e0431
Closes-Bug: #1609175

api-ref/source/v3/parameters.yaml

@@ -277,6 +277,25 @@ parent_region_id_query:
   in: query
   required: false
   type: string
+parents_as_ids:
+  description: |
+    The entire parent hierarchy will be included as
+    nested dictionaries in the response. It will contain
+    all projects ids found by traversing up the hierarchy
+    to the top-level project.
+  in: query
+  required: false
+  type: key-only, no value expected
+  min_version: 3.4
+parents_as_list:
+  description: |
+    The parent hierarchy will be included as a list in the response.
+    This list will contain the projects found by traversing up the
+    hierarchy to the top-level project.
+  in: query
+  required: false
+  type: key-only, no value expected
+  min_version: 3.4
 project_enabled_query:
   description: |
     If set to true, then only enabled projects will be returned. Any value
@@ -336,6 +355,24 @@ service_type_query:
   in: query
   required: false
   type: string
+subtree_as_ids:
+  description: |
+    The entire child hierarchy will be included as nested dictionaries
+    in the response. It will contain all the projects ids found by
+    traversing down the hierarchy.
+  in: query
+  required: false
+  type: key-only, no value expected
+  min_version: 3.4
+subtree_as_list:
+  description: |
+    The child hierarchy will be included as a list in the response.
+    This list will contain the projects found by traversing down
+    the hierarchy.
+  in: query
+  required: false
+  type: key-only, no value expected
+  min_version: 3.4
 type_4:
   description: |
     Filters the response by a MIME media type for the

api-ref/source/v3/projects.inc

@@ -135,6 +135,10 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - project_id: project_id_path
+   - parents_as_list: parents_as_list
+   - subtree_as_list: subtree_as_list
+   - parents_as_ids: parents_as_ids
+   - subtree_as_ids: subtree_as_ids
 
 Response Parameters
 -------------------
@@ -157,6 +161,18 @@ Response Example
 .. literalinclude:: ./samples/admin/project-show-response.json
    :language: javascript
 
+Response Example with ``parents_as_list``
+-----------------------------------------
+
+.. literalinclude:: ./samples/admin/project-show-parents-response.json
+   :language: javascript
+
+Response Example with ``subtree_as_list``
+-----------------------------------------
+
+.. literalinclude:: ./samples/admin/project-show-subtree-response.json
+   :language: javascript
+
 
 Update project
 ==============

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

@@ -0,0 +1,26 @@
+{
+    "project": {
+        "domain_id": "1789d1",
+        "enabled": true,
+        "id": "263fd9",
+        "links": {
+            "self": "http://example.com/identity/v3/projects/263fd9"
+        },
+        "name": "Dev Group A",
+        "parent_id": "183ab2",
+        "parents": [
+            {
+                "project": {
+                    "domain_id": "1789d1",
+                    "enabled": true,
+                    "id": "183ab2",
+                    "links": {
+                        "self": "http://example.com/identity/v3/projects/183ab2"
+                    },
+                    "name": "Dev Group A Parent",
+                    "parent_id": null
+                }
+            }
+        ]
+    }
+}

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

@@ -0,0 +1,50 @@
+{
+    "project": {
+        "domain_id": "1789d1",
+        "enabled": true,
+        "id": "263fd9",
+        "links": {
+            "self": "http://example.com/identity/v3/projects/263fd9"
+        },
+        "name": "Dev Group A",
+        "parent_id": "183ab2",
+        "subtree": [
+            {
+                "project": {
+                    "domain_id": "1789d1",
+                    "enabled": true,
+                    "id": "9n1jhb",
+                    "links": {
+                        "self": "http://example.com/identity/v3/projects/9n1jhb"
+                    },
+                    "name": "Dev Group A Child 1",
+                    "parent_id": "263fd9"
+                }
+            },
+            {
+                "project": {
+                    "domain_id": "1789d1",
+                    "enabled": true,
+                    "id": "4b6aa1",
+                    "links": {
+                        "self": "http://example.com/identity/v3/projects/4b6aa1"
+                    },
+                    "name": "Dev Group A Child 2",
+                    "parent_id": "263fd9"
+                }
+            },
+            {
+                "project": {
+                    "domain_id": "1789d1",
+                    "enabled": true,
+                    "id": "b76eq8",
+                    "links": {
+                        "self": "http://example.com/identity/v3/projects/b76xq8"
+                    },
+                    "name": "Dev Group A Grandchild",
+                    "parent_id": "4b6aa1"
+                }
+            }
+        ]
+    }
+}