[placement] api-ref: add description for 1.29

Add description for nested resource providers
in allocation candidates, Placement API microversion 1.29
in the Placement API reference.

Change-Id: I22c2068ae860c1ef2cbdb0801e85a40acc2a097a
Implements: blueprint nested-resource-providers-allocation-candidates

placement-api-ref/source/allocation_candidates.inc

@@ -44,16 +44,24 @@ Response (microversions 1.12 - )
 .. rest_parameters:: parameters.yaml
 
   - allocation_requests: allocation_requests
-  - provider_summaries: provider_summaries
+  - provider_summaries: provider_summaries_1_12
   - allocations: allocations_by_resource_provider
   - resources: resources
   - capacity: capacity
   - used: used
   - traits: traits_1_17
+  - parent_provider_uuid: resource_provider_parent_provider_uuid_response_1_29
+  - root_provider_uuid: resource_provider_root_provider_uuid_1_29
 
-Response Example (microversions 1.17 - )
+Response Example (microversions 1.29 - )
 ----------------------------------------
 
+.. literalinclude:: ./samples/allocation_candidates/get-allocation_candidates-1.29.json
+   :language: javascript
+
+Response Example (microversions 1.17 - 1.28)
+--------------------------------------------
+
 .. literalinclude:: ./samples/allocation_candidates/get-allocation_candidates-1.17.json
    :language: javascript
 

placement-api-ref/source/parameters.yaml

@@ -363,10 +363,20 @@ provider_summaries:
   in: body
   required: true
   description: >
-    A dictionary keyed by resource provider UUID,
-    of dictionaries of inventory/capacity information. The list of traits
-    the resource provider has associated with it is included in version `1.17`
-    and above.
+    A dictionary keyed by resource provider UUID included in the
+    ``allocation_requests``, of dictionaries of inventory/capacity information.
+provider_summaries_1_12:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary keyed by resource provider UUID included in the
+    ``allocation_requests``, of dictionaries of inventory/capacity information.
+    The list of traits the resource provider has associated with it is included
+    in version 1.17 and above.
+    Starting from microversion 1.29, the provider summaries include
+    all resource providers in the same resource provider tree that has one
+    or more resource providers included in the ``allocation_requests``.
 reserved: &reserved
   type: integer
   in: body
@@ -474,6 +484,20 @@ resource_provider_parent_provider_uuid_response_1_14:
   description: >
     The UUID of the immediate parent of the resource provider.
   min_version: 1.14
+resource_provider_parent_provider_uuid_response_1_29:
+  type: string
+  in: body
+  required: true
+  description: >
+    The UUID of the immediate parent of the resource provider.
+  min_version: 1.29
+resource_provider_root_provider_uuid_1_29:
+  type: string
+  in: body
+  required: true
+  description: >
+    UUID of the top-most provider in this provider tree.
+  min_version: 1.29
 resource_provider_root_provider_uuid_no_min: &resource_provider_root_provider_uuid_no_min
   type: string
   in: body

placement-api-ref/source/samples/allocation_candidates/get-allocation_candidates-1.29.json

@@ -0,0 +1,88 @@
+{
+    "allocation_requests": [
+        {
+            "allocations": {
+                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
+                    "resources": {
+                        "DISK_GB": 100
+                    }
+                },
+                "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
+                    "resources": {
+                        "VCPU": 1,
+                        "MEMORY_MB": 1024
+                    }
+                }
+            }
+        },
+        {
+            "allocations": {
+                "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
+                    "resources": {
+                        "DISK_GB": 100
+                    }
+                },
+                "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
+                    "resources": {
+                        "VCPU": 1,
+                        "MEMORY_MB": 1024
+                    }
+                }
+            }
+        }
+    ],
+    "provider_summaries": {
+        "a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
+            "resources": {
+                "DISK_GB": {
+                    "used": 0,
+                    "capacity": 1900
+                }
+            },
+            "traits": ["MISC_SHARES_VIA_AGGREGATE"],
+            "parent_provider_uuid": null,
+            "root_provider_uuid": "a99bad54-a275-4c4f-a8a3-ac00d57e5c64"
+        },
+        "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
+            "resources": {
+                "VCPU": {
+                    "used": 0,
+                    "capacity": 384
+                },
+                "MEMORY_MB": {
+                    "used": 0,
+                    "capacity": 196608
+                }
+            },
+            "traits": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"],
+            "parent_provider_uuid": null,
+            "root_provider_uuid": "35791f28-fb45-4717-9ea9-435b3ef7c3b3"
+        },
+        "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
+            "resources": {
+                "VCPU": {
+                    "used": 0,
+                    "capacity": 384
+                },
+                "MEMORY_MB": {
+                    "used": 0,
+                    "capacity": 196608
+                }
+            },
+            "traits": ["HW_NIC_SRIOV"],
+            "parent_provider_uuid": null,
+            "root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
+        },
+        "f5120cad-67d9-4f20-9210-3092a79a28cf": {
+            "resources": {
+                "SRIOV_NET_VF": {
+                    "used": 0,
+                    "capacity": 8
+                }
+            },
+            "traits": [],
+            "parent_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd",
+            "root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
+        }
+    }
+}