Add missing volume APIs

A bunch of volume APIs are missing in current documentation, such
as os-reserve/os-unreserve/os-begin_detaching/os-roll_detaching
os-initialize_connection/os-terminate_connection, this patch is aim to
add the missing APIs.

Change-Id: If0732aa94db4e8cdef30a2be0c53314b507ee002
Closes-bug: #1761049

api-ref/source/v3/parameters.yaml

@@ -1912,6 +1912,12 @@ os-backup-project-attr:project_id:
   required: true
   type: string
   min_version: 3.18
+os-begin_detaching:
+  description: |
+    The ``os-begin_detaching`` action.
+  in: body
+  required: true
+  type: object
 os-detach:
   description: |
     The ``os-detach`` action.
@@ -1948,6 +1954,18 @@ os-force_detach:
   in: body
   required: true
   type: object
+os-initialize_connection:
+  description: |
+    The ``os-initialize_connection`` action.
+  in: body
+  required: true
+  type: object
+os-reserve:
+  description: |
+    The ``os-reserve`` action.
+  in: body
+  required: true
+  type: object
 os-reset_status:
   description: |
     The ``os-reset_status`` action.
@@ -1960,6 +1978,12 @@ os-retype:
   in: body
   required: true
   type: object
+os-roll_detaching:
+  description: |
+    The ``os-roll_detaching`` action.
+  in: body
+  required: true
+  type: object
 OS-SCH-HNT:scheduler_hints:
   description: |
     The dictionary of data to send to the scheduler.
@@ -1984,6 +2008,12 @@ os-show_image_metadata:
   in: body
   require: true
   type: object
+os-terminate_connection:
+  description: |
+    The ``os-terminate_connection`` action.
+  in: body
+  require: true
+  type: object
 os-unmanage:
   description: |
     The ``os-unmanage`` action. This action removes
@@ -1991,6 +2021,12 @@ os-unmanage:
   in: body
   required: true
   type: object
+os-unreserve:
+  description: |
+    The ``os-unreserve`` action.
+  in: body
+  required: true
+  type: object
 os-unset_image_metadata:
   description: |
     The ``os-unset_image_metadata`` action. This

api-ref/source/v3/samples/volume-begin-detaching-request.json

@@ -0,0 +1,3 @@
+{
+  "os-begin_detaching": {}
+}

api-ref/source/v3/samples/volume-initialize-connection-request.json

@@ -0,0 +1,13 @@
+{
+    "os-initialize_connection": {
+        "connector":{
+            "platform":"x86_64",
+            "host": "node2",
+            "do_local_attach": false,
+            "ip": "192.168.13.101",
+            "os_type": "linux2",
+            "multipath": false,
+            "initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
+            }
+     }
+}

api-ref/source/v3/samples/volume-reserve-request.json

@@ -0,0 +1,3 @@
+{
+  "os-reserve": {}
+}

api-ref/source/v3/samples/volume-roll-detaching-request.json

@@ -0,0 +1,3 @@
+{
+   "os-roll_detaching": {}
+}

api-ref/source/v3/samples/volume-terminate-connection-request.json

@@ -0,0 +1,13 @@
+{
+  "os-terminate_connection": {
+      "connector": {
+          "platform": "x86_64",
+          "host": "node2",
+          "do_local_attach": false,
+          "ip": "192.168.13.101",
+          "os_type": "linux2",
+          "multipath": false,
+          "initiator": "iqn.1994-05.com.redhat:d16cbb5d31e5"
+          }
+      }
+}

api-ref/source/v3/samples/volume-unreserve-request.json

@@ -0,0 +1,3 @@
+{
+    "os-unreserve":{}
+}

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

@@ -590,3 +590,209 @@ Response Example
 
 .. literalinclude:: ./samples/volume-upload-to-image-response.json
    :language: javascript
+
+
+Reserve volume
+~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Mark volume as reserved. Specify the ``os-reserve`` action in the
+request body.
+
+Preconditions
+
+- Volume status must be ``available``.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-reserve: os-reserve
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-reserve-request.json
+   :language: javascript
+
+
+Unmark volume as reserved.
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Unmark volume as reserved. Specify the ``os-unreserve`` action in
+the request body.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-unreserve: os-unreserve
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-unreserve-request.json
+   :language: javascript
+
+
+Update volume status to detaching
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Update volume status to 'detaching'.. Specify the ``os-begin_detaching`` action
+in the request body.
+
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-begin_detaching: os-begin_detaching
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-begin-detaching-request.json
+   :language: javascript
+
+
+
+Roll back volume status to in-use
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Roll back volume status to 'in-use'. Specify the ``os-roll_detaching`` action
+in the request body.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-roll_detaching: os-roll_detaching
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-roll-detaching-request.json
+   :language: javascript
+
+
+Terminate volume attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Terminate volume attachment. Specify the ``os-terminate_connection``
+action in the request body.
+
+Preconditions
+
+- Volume status must be ``in-use``.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-terminate_connection: os-terminate_connection
+   - connector: connector
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-terminate-connection-request.json
+   :language: javascript
+
+
+
+Initialize volume attachment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/action
+
+Initialize volume attachment. Specify the ``os-initialize_connection``
+action in the request body.
+
+Response codes
+--------------
+
+.. rest_status_code:: success ../status.yaml
+
+   - 202
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_path
+   - os-initialize_connection: os-initialize_connection
+   - connector: connector
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/volume-initialize-connection-request.json
+   :language: javascript
+