[api-ref] Update snapshot/volume's metadata api-ref

Volume/Snapshot contains two kinds API for it's metadata: POST/PUT

POST is used for creatng or replacing the volume/snapshot's
metadata items that match keys. It doesn't modify items that
are not in the request.

PUT is used for replacing all the volume/snapshot's metadata
with the key-value pairs in the request.

Cinder's api-ref description is wrong. This patch fixed the
description and added the missing POST/PUT request.

Change-Id: I51128d32c9f70ba57d7d4cf0634a16ca566db95f

api-ref/source/v2/samples/snapshot-metadata-create-request.json

@@ -0,0 +1,5 @@
+{
+    "metadata": {
+        "key": "v2"
+    }
+}

api-ref/source/v2/samples/snapshot-metadata-create-response.json

@@ -0,0 +1,5 @@
+{
+    "metadata": {
+        "key": "v2"
+    }
+}

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

@@ -203,15 +203,50 @@ Response Example
    :language: javascript
 
 
+Create snapshot metadata
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v2/{tenant_id}/snapshots/{snapshot_id}/metadata
+
+Updates metadata for a snapshot.
+
+Creates or replaces metadata items that match keys. Does not modify items that
+are not in the request.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+   - tenant_id: tenant_id
+   - snapshot_id: snapshot_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/snapshot-metadata-create-request.json
+   :language: javascript
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/snapshot-metadata-create-response.json
+   :language: javascript
+
+
 Update snapshot metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. rest_method::  PUT /v2/{tenant_id}/snapshots/{snapshot_id}/metadata
 
-Updates metadata for a snapshot.
-
-Replaces metadata items that match keys. Does not modify items that
-are not in the request.
+Replaces all the snapshot's metadata with the key-value pairs in the request.
 
 
 Normal response codes: 200

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

@@ -449,7 +449,8 @@ Create volume metadata
 
 .. rest_method::  POST /v2/{tenant_id}/volumes/{volume_id}/metadata
 
-Creates metadata for a volume.
+Creates or replaces metadata for a volume. Does not modify items that are not
+in the request.
 
 Normal response codes: 202,
 
@@ -531,10 +532,7 @@ Update volume metadata
 
 .. rest_method::  PUT /v2/{tenant_id}/volumes/{volume_id}/metadata
 
-Updates metadata for a volume.
-
-Replaces metadata items that match keys. Does not modify items that
-are not in the request.
+Replaces all the volume's metadata with the key-value pairs in the request.
 
 
 Normal response codes: 200

api-ref/source/v3/samples/snapshot-metadata-create-request.json

@@ -0,0 +1,5 @@
+{
+    "metadata": {
+        "key": "v3"
+    }
+}

api-ref/source/v3/samples/snapshot-metadata-create-response.json

@@ -0,0 +1,5 @@
+{
+    "metadata": {
+        "key": "v3"
+    }
+}

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

@@ -209,15 +209,49 @@ Response Example
    :language: javascript
 
 
+Create a snapshot's metadata
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  POST /v3/{project_id}/snapshots/{snapshot_id}/metadata
+
+Updates metadata for a snapshot.
+
+Creates or replaces metadata items that match keys. Does not modify items that
+are not in the request.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - metadata: metadata
+   - project_id: project_id_path
+   - snapshot_id: snapshot_id
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/snapshot-metadata-create-request.json
+   :language: javascript
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/snapshot-metadata-create-response.json
+   :language: javascript
+
 Update a snapshot's metadata
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. rest_method::  PUT /v3/{project_id}/snapshots/{snapshot_id}/metadata
 
-Updates metadata for a snapshot.
-
-Replaces metadata items that match keys. Does not modify items that
-are not in the request.
+Replaces all the snapshot's metadata with the key-value pairs in the request.
 
 
 Normal response codes: 200

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

@@ -453,7 +453,8 @@ Create metadata for volume
 
 .. rest_method::  POST /v3/{project_id}/volumes/{volume_id}/metadata
 
-Creates metadata for a volume.
+Creates or replaces metadata for a volume. Does not modify items that are not
+in the request.
 
 Error response codes:202,
 
@@ -536,10 +537,7 @@ Update a volume's metadata
 
 .. rest_method::  PUT /v3/{project_id}/volumes/{volume_id}/metadata
 
-Updates metadata for a volume.
-
-Replaces metadata items that match keys. Does not modify items that
-are not in the request.
+Replaces all the volume's metadata with the key-value pairs in the request.
 
 
 Normal response codes: 200