Add API reference for cluster upgrade

Task: 30167
Story: 2002210

Change-Id: I18df7602a7f18128c77452dc8f91bd5e07b8c198

api-ref/source/clusters.inc

@@ -318,5 +318,62 @@ Response
 Response Example
 ----------------
 
-.. literalinclude:: samples/cluster-create-resp.json
-   :language: javascript
+.. literalinclude:: samples/cluster-resize-resp.json
+   :language: javascript
+
+
+Upgrade a cluster
+=================
+
+.. rest_method:: POST /v1/clusters/{cluster_ident}/actions/upgrade
+
+Resize a cluster.
+
+Response Codes
+--------------
+
+.. rest_status_code:: success status.yaml
+
+   - 202
+
+.. rest_status_code:: error status.yaml
+
+   - 401
+   - 403
+   - 404
+   - 409
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - cluster_ident: cluster_ident
+  - cluster_template: clustertemplate_id
+  - max_batch_size: max_batch_size
+  - nodegroup: nodegroup
+
+.. note::
+
+   The nodegroup is just a placeholder for future. It hasn't been supported
+   in Magnum now.
+
+Request Example
+----------------
+
+.. literalinclude:: samples/cluster-upgrade-req.json
+   :language: javascript
+
+Response
+--------
+
+.. rest_parameters:: parameters.yaml
+
+  - X-Openstack-Request-Id: request_id
+  - uuid: cluster_id
+
+Response Example
+----------------
+
+.. literalinclude:: samples/cluster-upgrade-resp.json
+   :language: javascript

api-ref/source/parameters.yaml

@@ -386,6 +386,12 @@ master_lb_enabled:
   in: body
   required: true
   type: boolean
+max_batch_size:
+  description: |
+    The max batch size each time when doing upgrade, default value is 1
+  in: body
+  required: false
+  type: int
 mservices:
   description: |
     A list of Magnum services.

api-ref/source/samples/cluster-resize-resp.json

@@ -0,0 +1,3 @@
+{
+   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
+}

api-ref/source/samples/cluster-upgrade-req.json

@@ -0,0 +1,5 @@
+{
+    "cluster_template": "e74c40e0-d825-11e2-a28f-0800200c9a66",
+    "max_batch_size": 1,
+    "nodegroup":　"production_group"
+}

api-ref/source/samples/cluster-upgrade-resp.json

@@ -0,0 +1,3 @@
+{
+   "uuid":"746e779a-751a-456b-a3e9-c883d734946f"
+}