Add api-ref documents for multi-instance-create

Add min_count and max_count parameters instruction.

Change-Id: Ie114b0670f7b3b3db494744fb349bea6a5480033
Implements: bp support-multiple-creation

api-ref/source/v1/instances.inc

@@ -67,6 +67,53 @@ Response
 
 **Example Create Instance: JSON response**
 
+.. literalinclude:: samples/instances/instance-create-resp.json
+   :language: javascript
+
+Create Multiple Instances
+=========================
+
+.. rest_method:: POST /instances
+
+Create Multiple Instances.
+
+There is a second kind of create call which can create multiple instances
+at once. This supports all the same parameters as create with a few additional
+attributes specific to multiple create.
+
+Error handling for multiple create is not as consistent as for single server
+create, and there is no guarantee that all the instances will be created
+successfully.
+
+Normal response codes: 201
+
+Error response codes: badRequest(400), unauthorized(401),
+forbidden(403), conflict(409)
+
+Request (Additional Parameters)
+-------------------------------
+
+These are the parameters beyond single create that are supported.
+
+.. rest_parameters:: parameters.yaml
+
+  - name: multi_instacne_name_body
+  - min_count(Optional): min_count_body
+  - max_count(Optional): max_count_body
+
+**Example Create Multiple Instance: JSON request**
+
+.. literalinclude:: samples/instances/multi-instance-create-req.json
+   :language: javascript
+
+Response
+--------
+
+The first instace will be returned. The returned paramaters is same to creating
+a single instance's.
+
+**Example Create Multiple Instance: JSON response**
+
 .. literalinclude:: samples/instances/instance-create-resp.json
    :language: javascript
 

api-ref/source/v1/parameters.yaml

@@ -190,6 +190,26 @@ lock_state:
   in: body
   required: true
   type: boolean
+max_count_body:
+  description: |
+      The max number of servers to be created. Defaults to the value of ``min_count``.
+  in: body
+  required: false
+  type: integer
+min_count_body:
+  description: |
+    The min number of servers to be created. Defaults to 1.
+  in: body
+  required: false
+  type: integer
+multi_instacne_name_body:
+  description: |
+    A base name for creating unique names during multiple create. A unique
+    string will be appended to the end of this base name for every instacne
+    created.
+  in: body
+  required: true
+  type: string
 network_info:
   description: |
     The port info in the requested network for the instance, with fixed_ip, mac_address, and

api-ref/source/v1/samples/instances/multi-instance-create-req.json

@@ -0,0 +1,17 @@
+{
+    "name": "test_instance",
+    "description": "this is a test instance",
+    "instance_type_uuid": "0607b5f3-6111-424d-ba46-f5de39a6fa69",
+    "image_uuid": "efe0a06f-ca95-4808-b41e-9f55b9c5eb98",
+    "networks": [
+        {
+            "net_id": "c1940655-8b8e-4370-b8f9-03ba1daeca31"
+        },
+        {
+            "net_id": "8e8ceb07-4641-4188-9b22-840755e92ee2",
+            "port_type": "10GE"
+        }
+    ],
+    "min_count": 2,
+    "max_count": 3
+}