From 145adf1a14eb6fecdf7a7f5b70f0c5d7fc4afc91 Mon Sep 17 00:00:00 2001
From: Tao Li <litao3721@126.com>
Date: Thu, 16 Feb 2017 17:12:19 +0800
Subject: [PATCH] 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               | 47 +++++++++++++++++++
 api-ref/source/v1/parameters.yaml             | 20 ++++++++
 .../instances/multi-instance-create-req.json  | 17 +++++++
 3 files changed, 84 insertions(+)
 create mode 100644 api-ref/source/v1/samples/instances/multi-instance-create-req.json

diff --git a/api-ref/source/v1/instances.inc b/api-ref/source/v1/instances.inc
index 26d8f204..92c27c54 100644
--- a/api-ref/source/v1/instances.inc
+++ b/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
 
diff --git a/api-ref/source/v1/parameters.yaml b/api-ref/source/v1/parameters.yaml
index b0ce7764..f5bd8ca6 100644
--- a/api-ref/source/v1/parameters.yaml
+++ b/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
diff --git a/api-ref/source/v1/samples/instances/multi-instance-create-req.json b/api-ref/source/v1/samples/instances/multi-instance-create-req.json
new file mode 100644
index 00000000..d11384a9
--- /dev/null
+++ b/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
+}