[placement] Add api-ref for POST resource provider

This provides simple documentation of the request
parameters when creating a resource provider.

Change-Id: I1fd189503f33da4febcd2e4dc5132f4c240c19b0

placement-api-ref/source/create-resource_providers-request.json

@@ -0,0 +1,4 @@
+{
+    "name": "NFS Share",
+    "uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f"
+}

placement-api-ref/source/parameters.yaml

@@ -118,6 +118,10 @@ resource_provider_name:
 resource_provider_uuid:
   <<: *resource_provider_uuid_path
   in: body
+resource_provider_uuid_opt:
+  <<: *resource_provider_uuid_path
+  in: body
+  required: false
 resource_providers:
   type: array
   in: body

placement-api-ref/source/resource_providers.inc

@@ -6,7 +6,7 @@ Resource providers are entities which provide consumable inventory of one or
 more classes of resource (such as disk or memory). They can be listed (with
 filters), created, updated and deleted.
 
-List Resource Providers
+List resource providers
 =======================
 
 .. rest_method:: GET /resource_providers
@@ -46,3 +46,37 @@ Response Example
 
 .. literalinclude:: get-resource_providers.json
    :language: javascript
+
+Create resource provider
+========================
+
+.. rest_method:: POST /resource_providers
+
+Create a new resource provider.
+
+Normal Response Codes: 201
+
+Error response codes: conflict(409)
+
+A `409 Conflict` response code will
+be returned if another resource provider exists with the provided name
+or uuid.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - name: resource_provider_name
+  - uuid: resource_provider_uuid_opt
+
+Request example
+---------------
+
+.. literalinclude:: create-resource_providers-request.json
+   :language: javascript
+
+Response
+--------
+
+No body content is returned on a successful POST.