From 3ebee7f64af511fa802af8b4826c85b1c6fe3c51 Mon Sep 17 00:00:00 2001
From: wangxiyuan <wangxiyuan@huawei.com>
Date: Wed, 14 Dec 2016 10:39:00 +0800
Subject: [PATCH] [api-ref]Add volumes/summary API doc

GET volumes/summary is introduced to Cinder from V3.12. This patch
add this API's doc.

Change-Id: I8d83e9308691bc4f1117aa47d40cba2daadd36ee
Closes-bug: #1616802
---
 api-ref/source/v3/parameters.yaml             | 24 ++++++++++++
 .../volumes-list-summary-response.json        |  6 +++
 api-ref/source/v3/volumes-v3-volumes.inc      | 38 +++++++++++++++++++
 3 files changed, 68 insertions(+)
 create mode 100644 api-ref/source/v3/samples/volumes-list-summary-response.json

diff --git a/api-ref/source/v3/parameters.yaml b/api-ref/source/v3/parameters.yaml
index 13b9b9f46..820da57ca 100644
--- a/api-ref/source/v3/parameters.yaml
+++ b/api-ref/source/v3/parameters.yaml
@@ -13,6 +13,12 @@ admin_project_id:
   in: path
   required: false
   type: string
+all_tenants:
+  description: |
+    Shows details for all projects.
+  in: path
+  required: false
+  type: string
 backup_id:
   description: |
     The UUID for a backup.
@@ -1598,6 +1604,18 @@ total_capacity:
   in: body
   required: true
   type: string
+total_count:
+  description: |
+    Total number of volumes.
+  in: body
+  required: true
+  type: integer
+total_size:
+  description: |
+    Total size of volumes in GB.
+  in: body
+  required: true
+  type: integer
 totalBackupGigabytesUsed:
   description: |
     The total number of backups gibibytes (GiB) used.
@@ -1687,6 +1705,12 @@ volume:
   in: body
   required: true
   type: object
+volume-summary:
+  description: |
+    Dictionary of ``volume-summary`` objects.
+  in: body
+  required: true
+  type: object
 volume_1:
   description: |
     A ``volume`` object.
diff --git a/api-ref/source/v3/samples/volumes-list-summary-response.json b/api-ref/source/v3/samples/volumes-list-summary-response.json
new file mode 100644
index 000000000..53a78f7da
--- /dev/null
+++ b/api-ref/source/v3/samples/volumes-list-summary-response.json
@@ -0,0 +1,6 @@
+{
+  "volume-summary": {
+    "total_size": 4,
+    "total_count": 4
+  }
+}
\ No newline at end of file
diff --git a/api-ref/source/v3/volumes-v3-volumes.inc b/api-ref/source/v3/volumes-v3-volumes.inc
index 39d1ae6d9..4a9ffcbb7 100644
--- a/api-ref/source/v3/volumes-v3-volumes.inc
+++ b/api-ref/source/v3/volumes-v3-volumes.inc
@@ -568,3 +568,41 @@ Response Example
 
 .. literalinclude:: ./samples/volume-metadata-update-response.json
    :language: javascript
+
+
+
+Get volumes summary
+===================
+
+.. rest_method::  GET /v3/{project_id}/volumes/summary
+
+Display volumes summary with total number of volumes and total size in GB
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - all_tenants: all_tenants
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - volume-summary: volume-summary
+   - total_size: total_size
+   - total_count: total_count
+
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/volumes-list-summary-response.json
+   :language: javascript