[placement] add api-ref for GET /resource_providers

This provides simple documentation of the response body and query
parameters when listing resource providers.

Change-Id: Ic8db81b5f17d4c380b64b3da24e525297db18584

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

@@ -0,0 +1,50 @@
+{
+  "resource_providers": [
+    {
+      "generation": 1,
+      "uuid": "99c09379-6e52-4ef8-9a95-b9ce6f68452e",
+      "links": [
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e",
+          "rel": "self"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/aggregates",
+          "rel": "aggregates"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/inventories",
+          "rel": "inventories"
+        },
+        {
+          "href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/usages",
+          "rel": "usages"
+        }
+      ],
+      "name": "vgr.localdomain"
+    },
+    {
+      "generation": 2,
+      "uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5",
+      "links": [
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5",
+          "rel": "self"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/aggregates",
+          "rel": "aggregates"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/inventories",
+          "rel": "inventories"
+        },
+        {
+          "href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/usages",
+          "rel": "usages"
+        }
+      ],
+      "name": "pony1"
+    }
+  ]
+}

placement-api-ref/source/index.rst

@@ -44,3 +44,52 @@ Response Example
 
 .. literalinclude:: get-root.json
    :language: javascript
+
+==================
+Resource Providers
+==================
+
+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
+=======================
+
+.. rest_method:: GET /resource_providers
+
+List an optionally filtered collection of resource providers.
+
+Normal Response Codes: 200
+
+Request
+-------
+
+Several query parameters are available to filter the returned list of
+resource providers. If multiple different parameters are provided, the results
+of all filters are merged with a boolean `AND`.
+
+.. rest_parameters:: parameters.yaml
+
+  - resources: resources_query
+  - member_of: member_of
+  - uuid: resource_provider_uuid_query
+  - name: resource_provider_name_query
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - resource_providers: resource_providers
+  - generation: resource_provider_generation
+  - uuid: resource_provider_uuid
+  - links: resource_provider_links
+  - name: resource_provider_name
+
+
+Response Example
+----------------
+
+.. literalinclude:: get-resource_providers.json
+   :language: javascript

placement-api-ref/source/parameters.yaml

@@ -1,3 +1,65 @@
+member_of:
+  type: string
+  in: query
+  required: false
+  description: >
+    A comma-separated list of strings representing aggregate uuids.
+    The returned resource providers must be associated with at
+    least one of the aggregates identified by uuid.
+resource_provider_name_query:
+  type: string
+  in: query
+  required: false
+  description: >
+    The name of a resource provider to filter the list.
+resource_provider_uuid_query:
+  type: string
+  in: query
+  required: false
+  description: >
+    The uuid of a resource provider to filter the list.
+resources_query:
+  type: string
+  in: query
+  required: false
+  description: |
+    A comma-separated list of strings indicating an amount of
+    resource of a specified class that a provider must have the
+    capacity to serve::
+
+        resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
+
+resource_provider_generation:
+  type: integer
+  in: body
+  required: true
+  description: >
+    A consistent view marker that assists with the management of
+    concurrent resource provider updates.
+resource_provider_links:
+  type: array
+  in: body
+  required: true
+  description: >
+    A list of links associated with one resource provider.
+resource_provider_name:
+  type: string
+  in: body
+  required: true
+  description: >
+    The name of one resource provider.
+resource_provider_uuid:
+  type: string
+  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.
 version_id:
   type: string
   in: body