[placement] Add api-ref for RP allocations

This provides simple documentation of the path and response
body parameters when listing resource provider allocations.

Co-Authored-by: Andrey Volkov <avolkov@gmail.com>

Change-Id: I40fcbc3077151227f33c6a021229b5c549889bbe

placement-api-ref/source/get-resource_provider_allocations.json

@@ -0,0 +1,23 @@
+{
+    "allocations": {
+        "56785a3f-6f1c-4fec-af0b-0faf075b1fcb": {
+            "resources": {
+                "MEMORY_MB": 256,
+                "VCPU": 1
+            }
+        },
+        "9afd5aeb-d6b9-4dea-a588-1e6327a91834": {
+            "resources": {
+                "MEMORY_MB": 512,
+                "VCPU": 2
+            }
+        },
+        "9d16a611-e7f9-4ef3-be26-c61ed01ecefb": {
+            "resources": {
+                "MEMORY_MB": 1024,
+                "VCPU": 1
+            }
+        }
+    },
+    "resource_provider_generation": 12
+}

placement-api-ref/source/index.rst

@@ -23,3 +23,4 @@ Openstack Placement API concepts, please refer to the
 .. include:: traits.inc
 .. include:: resource_provider_traits.inc
 .. include:: allocations.inc
+.. include:: resource_provider_allocations.inc

placement-api-ref/source/parameters.yaml

@@ -174,6 +174,12 @@ resource_classes:
   required: true
   description: >
     A list of ``resource_class`` objects.
+resource_provider_allocations:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of allocation records keyed by consumer uuid.
 resource_provider_generation:
   type: integer
   in: body

placement-api-ref/source/resource_provider_allocations.inc

@@ -0,0 +1,40 @@
+=============================
+Resource provider allocations
+=============================
+
+See `Allocations`_ for a description.
+
+List resource provider allocations
+==================================
+
+Return a representation of all allocations made against this resource
+provider, keyed by consumer uuid. Each allocation includes one or more
+classes of resource and the amount consumed.
+
+.. rest_method:: GET /resource_providers/{uuid}/allocations
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - allocations: resource_provider_allocations
+  - resources: resources
+  - resource_provider_generation: resource_provider_generation
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_provider_allocations.json
+   :language: javascript