[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

@@ -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.

api-ref/source/v3/samples/volumes-list-summary-response.json

@@ -0,0 +1,6 @@
+{
+  "volume-summary": {
+    "total_size": 4,
+    "total_count": 4
+  }
+}

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