api-ref: v2 API does not mention GET volume metadata by key

In v2:
Add an explanation regarding GET for volume metadata for a specific key
and some parameters regarding key, because those are missed.
Modify prameters of volume_id and key for DELETE, because those should be in path.
In v3:
Add explanations regarding GET and DELETE for volume metadata for a specific key
and some parameters regarding key, because those are missed.

Change-Id: I0a9dd9b62bb196db97af80dc928501ad7c57df6e
Closes-Bug: #1669142

api-ref/source/v2/parameters.yaml

@@ -45,6 +45,20 @@ hostname:
   in: path
   required: false
   type: string
+key_1:
+  description: |
+    The metadata key name for the metadata that you
+    want to remove.
+  in: path
+  required: true
+  type: string
+key_2:
+  description: |
+    The metadata key name for the metadata that you
+    want to see.
+  in: path
+  required: true
+  type: string
 qos_id:
   description: |
     The ID of the QoS specification.

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

@@ -575,6 +575,43 @@ Response Example
 
 
 
+Show volume metadata for a specific key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v2/{tenant_id}/volumes/{volume_id}/metadata/{key}
+
+Shows metadata for a volume for a specific key.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - tenant_id: tenant_id
+   - volume_id: volume_id_1
+   - key: key_2
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata_3
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-metadata-show-response.json
+   :language: javascript
+
+
+
 
 Delete volume metadata
 ~~~~~~~~~~~~~~~~~~~~~~
@@ -592,5 +629,5 @@ Request
 .. rest_parameters:: parameters.yaml
 
    - tenant_id: tenant_id
-   - volume_id: volume_id
-   - key: key
+   - volume_id: volume_id_1
+   - key: key_1

api-ref/source/v3/parameters.yaml

@@ -75,6 +75,20 @@ hostname:
   in: path
   required: false
   type: string
+key_1:
+  description: |
+    The metadata key name for the metadata that you
+    want to remove.
+  in: path
+  required: true
+  type: string
+key_2:
+  description: |
+    The metadata key name for the metadata that you
+    want to see.
+  in: path
+  required: true
+  type: string
 project_id_path:
   description: |
     The UUID of the project in a multi-tenancy cloud.

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

@@ -575,6 +575,63 @@ Response Example
    :language: javascript
 
 
+Show a volume's metadata for a specific key
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{project_id}/volumes/{volume_id}/metadata/{key}
+
+Shows metadata for a volume for a specific key.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_1
+   - key: key_2
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata_3
+
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volume-metadata-show-response.json
+   :language: javascript
+
+
+
+Delete a volume's metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v3/{project_id}/volumes/{volume_id}/metadata/{key}
+
+Deletes metadata for a volume.
+
+Normal response codes: 200
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - volume_id: volume_id_1
+   - key: key_1
+
+
 
 Get volumes summary
 ~~~~~~~~~~~~~~~~~~~