[placement] Add api-ref for GET RP inventories

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

Change-Id: Id4ed2450ab70fc63d47dabb21c4a9b21f25d85b1

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

@@ -0,0 +1,29 @@
+{
+    "inventories": {
+        "DISK_GB": {
+            "allocation_ratio": 1.0,
+            "max_unit": 35,
+            "min_unit": 1,
+            "reserved": 0,
+            "step_size": 1,
+            "total": 35
+        },
+        "MEMORY_MB": {
+            "allocation_ratio": 1.5,
+            "max_unit": 5825,
+            "min_unit": 1,
+            "reserved": 512,
+            "step_size": 1,
+            "total": 5825
+        },
+        "VCPU": {
+            "allocation_ratio": 16.0,
+            "max_unit": 4,
+            "min_unit": 1,
+            "reserved": 0,
+            "step_size": 1,
+            "total": 4
+        }
+    },
+    "resource_provider_generation": 7
+}

placement-api-ref/source/index.rst

@@ -14,3 +14,4 @@ Openstack Placement API concepts, please refer to the
 
 .. include:: root.inc
 .. include:: resource_providers.inc
+.. include:: inventories.inc

placement-api-ref/source/inventories.inc

@@ -0,0 +1,44 @@
+=============================
+Resource provider inventories
+=============================
+
+Each resource provider has inventory records for one or more classes
+of resources. An inventory record contains information about the total
+and reserved amounts of the resource and any consumption constraints
+for that resource against the provider.
+
+List resource provider inventories
+==================================
+
+.. rest_method:: GET /resource_providers/{uuid}/inventories
+
+Normal Response Codes: 200
+
+Error response codes: itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - inventories: inventories
+  - resource_provider_generation: resource_provider_generation
+  - allocation_ratio: allocation_ratio
+  - max_unit: max_unit
+  - min_unit: min_unit
+  - reserved: reserved
+  - step_size: step_size
+  - total: total
+
+Response Example
+----------------
+
+.. literalinclude:: get-inventories.json
+   :language: javascript

placement-api-ref/source/parameters.yaml

@@ -1,3 +1,12 @@
+# variables in path
+resource_provider_uuid_path: &resource_provider_uuid_path
+  type: string
+  in: path
+  required: true
+  description: >
+    The uuid of a resource provider.
+
+# variables in query
 member_of:
   type: string
   in: query
@@ -13,11 +22,9 @@ resource_provider_name_query:
   description: >
     The name of a resource provider to filter the list.
 resource_provider_uuid_query:
-  type: string
+  <<: *resource_provider_uuid_path
   in: query
   required: false
-  description: >
-    The uuid of a resource provider to filter the list.
 resources_query:
   type: string
   in: query
@@ -29,6 +36,51 @@ resources_query:
 
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
 
+# variables in body
+allocation_ratio:
+  type: float
+  in: body
+  required: true
+  description: |
+    It is used in determining whether consumption of the resource of
+    the provider can exceed physical constraints.
+
+    For example, for a vCPU resource with::
+
+        allocation_ratio = 16.0
+        total = 8
+
+    Overall capacity is equal to 128 vCPUs.
+inventories:
+  type: object
+  in: body
+  required: true
+  description: >
+    A dictionary of inventories keyed by resource classes.
+max_unit: &max_unit
+  type: integer
+  in: body
+  required: true
+  description: >
+    A maximum amount any single allocation against an inventory can have.
+min_unit:
+  type: integer
+  in: body
+  required: true
+  description: >
+    A minimum amount any single allocation against an inventory can have.
+reserved:
+  type: integer
+  in: body
+  required: true
+  description: >
+    The amount of the resource a provider has reserved for its own use.
+resource_class:
+  type: string
+  in: body
+  required: true
+  description: >
+    The name of the resource class.
 resource_provider_generation:
   type: integer
   in: body
@@ -49,17 +101,28 @@ resource_provider_name:
   description: >
     The name of one resource provider.
 resource_provider_uuid:
-  type: string
+  <<: *resource_provider_uuid_path
   in: body
-  required: true
-  description: >
-    The UUID for one resource provider.
 resource_providers:
   type: array
   in: body
   required: true
   description: >
     A list of ``resource_provider`` objects.
+step_size:
+  type: integer
+  in: body
+  required: true
+  description: >
+    A representation of the divisible amount of the resource
+    that may be requested. For example, step_size = 5 means
+    that only values divisible by 5 (5, 10, 15, etc.) can be requested.
+total:
+  type: integer
+  in: body
+  required: true
+  description: >
+    The actual amount of the resource that the provider can accommodate.
 version_id:
   type: string
   in: body