[placement] Add api-ref for PUT RP inventories

This provides simple documentation of the request and response body
parameters when setting or replacing all inventories for a resource provider.

Change-Id: I720f5b6792b9f4ced905aef31715a835b07be504

placement-api-ref/source/inventories.inc

@@ -42,3 +42,56 @@ Response Example
 
 .. literalinclude:: get-inventories.json
    :language: javascript
+
+Update resource provider inventories
+====================================
+
+Replaces the set of inventory records for the resource provider identified by `{uuid}`.
+
+.. rest_method:: PUT /resource_providers/{uuid}/inventories
+
+Normal Response Codes: 200
+
+Error response codes: badRequest(400), itemNotFound(404), conflict(409)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - uuid: resource_provider_uuid_path
+  - resource_provider_generation: resource_provider_generation
+  - inventories: inventories
+  - allocation_ratio: allocation_ratio_opt
+  - max_unit: max_unit_opt
+  - min_unit: min_unit_opt
+  - reserved: reserved_opt
+  - step_size: step_size_opt
+  - total: total
+
+Request example
+---------------
+
+.. literalinclude:: update-inventories-request.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_provider_generation: resource_provider_generation
+  - inventories: inventories
+  - allocation_ratio: allocation_ratio
+  - max_unit: max_unit
+  - min_unit: min_unit
+  - reserved: reserved
+  - step_size: step_size
+  - total: total
+
+Response Example
+----------------
+
+.. literalinclude:: update-inventories.json
+   :language: javascript
+

placement-api-ref/source/parameters.yaml

@@ -37,7 +37,7 @@ resources_query:
         resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
 
 # variables in body
-allocation_ratio:
+allocation_ratio: &allocation_ratio
   type: float
   in: body
   required: true
@@ -51,6 +51,9 @@ allocation_ratio:
         total = 8
 
     Overall capacity is equal to 128 vCPUs.
+allocation_ratio_opt:
+  <<: *allocation_ratio
+  required: false
 inventories:
   type: object
   in: body
@@ -63,18 +66,27 @@ max_unit: &max_unit
   required: true
   description: >
     A maximum amount any single allocation against an inventory can have.
-min_unit:
+max_unit_opt:
+  <<: *max_unit
+  required: false
+min_unit: &min_unit
   type: integer
   in: body
   required: true
   description: >
     A minimum amount any single allocation against an inventory can have.
-reserved:
+min_unit_opt:
+  <<: *min_unit
+  required: false
+reserved: &reserved
   type: integer
   in: body
   required: true
   description: >
     The amount of the resource a provider has reserved for its own use.
+reserved_opt:
+  <<: *reserved
+  required: false
 resource_class:
   type: string
   in: body
@@ -109,7 +121,7 @@ resource_providers:
   required: true
   description: >
     A list of ``resource_provider`` objects.
-step_size:
+step_size: &step_size
   type: integer
   in: body
   required: true
@@ -117,6 +129,9 @@ step_size:
     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.
+step_size_opt:
+  <<: *step_size
+  required: false
 total:
   type: integer
   in: body

placement-api-ref/source/update-inventories-request.json

@@ -0,0 +1,16 @@
+{
+    "inventories": {
+        "MEMORY_MB": {
+            "allocation_ratio": 2.0,
+            "max_unit": 16,
+            "step_size": 4,
+            "total": 128
+        },
+        "VCPU": {
+            "allocation_ratio": 10.0,
+            "reserved": 2,
+            "total": 64
+        }
+    },
+    "resource_provider_generation": 1
+}

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

@@ -0,0 +1,21 @@
+{
+    "inventories": {
+        "MEMORY_MB": {
+            "allocation_ratio": 2.0,
+            "max_unit": 16,
+            "min_unit": 1,
+            "reserved": 0,
+            "step_size": 4,
+            "total": 128
+        },
+        "VCPU": {
+            "allocation_ratio": 10.0,
+            "max_unit": 2147483647,
+            "min_unit": 1,
+            "reserved": 2,
+            "step_size": 1,
+            "total": 64
+        }
+    },
+    "resource_provider_generation": 2
+}