Add missing retype API documentation

Now retype is missing in v2/v3 API documentation.
Add it in doc.

Change-Id: I2ba0d7b993a5b3e21c396ed3d0862808e0daf0b3
Closes-Bug: #1603293

api-ref/source/v2/parameters.yaml

@@ -71,6 +71,12 @@ key_2:
   in: path
   required: true
   type: string
+project_id_path:
+  description: |
+    The UUID of the project in a multi-tenancy cloud.
+  in: path
+  required: false
+  type: string
 qos_id:
   description: |
     The ID of the QoS specification.
@@ -944,6 +950,13 @@ metadata_items:
   in: body
   required: true
   type: integer
+migration_policy:
+  description: |
+    Specify if make migration when retyping volume, the value is 'on-demand'
+    or 'never'.
+  in: body
+  required: false
+  type: string
 migration_status:
   description: |
     The volume migration status.
@@ -1093,6 +1106,12 @@ new_size:
   in: body
   required: true
   type: integer
+new_type:
+  description: |
+    The new volume type that volume is changed with.
+  in: body
+  required: true
+  type: string
 object_count:
   description: |
     The number of objects in the backup.
@@ -1147,6 +1166,12 @@ os-reset_status:
   in: body
   required: true
   type: object
+os-retype:
+  description: |
+    The ``os-retype`` action.
+  in: body
+  required: true
+  type: object
 OS-SCH-HNT:scheduler_hints:
   description: |
     The dictionary of data to send to the scheduler.
@@ -1765,3 +1790,9 @@ volumes:
   in: body
   required: true
   type: array
+volumes:
+  description: |
+    A list of ``volume`` objects.
+  in: body
+  required: true
+  type: array

api-ref/source/v2/samples/volume-os-retype-request.json

@@ -0,0 +1,6 @@
+{
+    "os-retype": {
+        "new_type": "dedup-tier-replicaton",
+        "migration_policy": "never"
+        }
+}

api-ref/source/v2/volumes-v2-volumes-actions.inc

@@ -305,3 +305,39 @@ Request Example
 
 
 
+Retype volume
+~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{project_id}/volumes/{volume_id}/action
+
+Change type of existing volume. Specify the ``os-retype`` action in the request body.
+
+Change the volume type of exisiting volume, Cinder may migrate the volume to
+proper volume host according to the new volume type.
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - new_type: new_type
+   - migration_policy: migration_policy
+   - os-retype: os-retype
+   - volume_id: volume_id_path
+   - project_id: project_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-retype-request.json
+   :language: javascript
+
+
+
+
+
+
+

api-ref/source/v3/parameters.yaml

@@ -1134,6 +1134,13 @@ metadata_items:
   in: body
   required: true
   type: integer
+migration_policy:
+  description: |
+    Specify if make migration when retyping volume, the value is 'on-demand'
+    or 'never'.
+  in: body
+  required: false
+  type: string
 migration_status:
   description: |
     The volume migration status.
@@ -1301,6 +1308,12 @@ new_size:
   in: body
   required: true
   type: integer
+new_type:
+  description: |
+    The new volume type that volume is changed with.
+  in: body
+  required: true
+  type: string
 object_count:
   description: |
     The number of objects in the backup.
@@ -1355,6 +1368,12 @@ os-reset_status:
   in: body
   required: true
   type: object
+os-retype:
+  description: |
+    The ``os-retype`` action.
+  in: body
+  required: true
+  type: object
 OS-SCH-HNT:scheduler_hints:
   description: |
     The dictionary of data to send to the scheduler.

api-ref/source/v3/samples/volume-os-retype-request.json

@@ -0,0 +1,6 @@
+{
+    "os-retype": {
+        "new_type": "dedup-tier-replicaton",
+        "migration_policy": "never"
+        }
+}

api-ref/source/v3/volumes-v3-volumes-actions.inc

@@ -302,3 +302,39 @@ Request Example
 
 
 
+Retype a volume
+~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Change type of existing volume. Specify the ``os-retype`` action in the request body.
+
+Change the volume type of exisiting volume, Cinder may migrate the volume to
+proper volume host according to the new volume type.
+
+Normal response codes: 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - new_type: new_type
+   - migration_policy: migration_policy
+   - os-retype: os-retype
+   - volume_id: volume_id_path
+   - project_id: project_id_path
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-os-retype-request.json
+   :language: javascript
+
+
+
+
+
+
+