From 0ce6c4de800f386aeee25632f9017910d58aecc6 Mon Sep 17 00:00:00 2001
From: Keisuke Kuroki <ke-kuroki@kddilabs.jp>
Date: Thu, 9 Mar 2017 12:12:08 +0900
Subject: [PATCH] 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        | 14 ++++++
 api-ref/source/v2/volumes-v2-volumes.inc | 41 ++++++++++++++++-
 api-ref/source/v3/parameters.yaml        | 14 ++++++
 api-ref/source/v3/volumes-v3-volumes.inc | 57 ++++++++++++++++++++++++
 4 files changed, 124 insertions(+), 2 deletions(-)

diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index 3d9a6563fe4..2a7f5c7efbe 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/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.
diff --git a/api-ref/source/v2/volumes-v2-volumes.inc b/api-ref/source/v2/volumes-v2-volumes.inc
index 709abf0e39f..942c783e489 100644
--- a/api-ref/source/v2/volumes-v2-volumes.inc
+++ b/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
diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 390dd14dbd9..37c6222ccdf 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/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.
diff --git a/api-ref/source/v3/volumes-v3-volumes.inc b/api-ref/source/v3/volumes-v3-volumes.inc
index 14897a9fa8f..1ec89b38e2f 100644
--- a/api-ref/source/v3/volumes-v3-volumes.inc
+++ b/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
 ~~~~~~~~~~~~~~~~~~~