[placement] api-ref: add traits parameter

In the "List allocation candidates" API,
the 'traits' parameter is missing.
So add it and update examples.

Change-Id: I4a307759f9e8fa80d003d92142f8e99b2c09c9fe
Partial-Bug: #1778670

placement-api-ref/source/allocation_candidates.inc

@@ -49,10 +49,17 @@ Response (microversions 1.12 - )
   - resources: resources
   - capacity: capacity
   - used: used
+  - traits: traits_1_17
 
-Response Example (microversions 1.12 - )
+Response Example (microversions 1.17 - )
 ----------------------------------------
 
+.. literalinclude:: ./samples/allocation_candidates/get-allocation_candidates-1.17.json
+   :language: javascript
+
+Response Example (microversions 1.12 - 1.16)
+--------------------------------------------
+
 .. literalinclude:: ./samples/allocation_candidates/get-allocation_candidates-1.12.json
    :language: javascript
 

placement-api-ref/source/parameters.yaml

@@ -523,12 +523,15 @@ total:
   required: true
   description: >
     The actual amount of the resource that the provider can accommodate.
-traits:
+traits: &traits
   type: array
   in: body
   required: true
   description: >
     A list of traits.
+traits_1_17:
+  <<: *traits
+  min_version: 1.17
 used:
   type: integer
   in: body

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

@@ -0,0 +1,71 @@
+{
+    "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": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"]
+        },
+        "915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
+            "resources": {
+                "VCPU": {
+                    "used": 0,
+                    "capacity": 384
+                },
+                "MEMORY_MB": {
+                    "used": 0,
+                    "capacity": 196608
+                }
+            },
+            "traits": ["HW_NIC_SRIOV"]
+        },
+        "35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
+            "resources": {
+                "VCPU": {
+                    "used": 0,
+                    "capacity": 384
+                },
+                "MEMORY_MB": {
+                    "used": 0,
+                    "capacity": 196608
+                }
+            },
+            "traits": []
+        }
+    }
+}