Add API document for quota usage.

This patch adds a new API document for quota usage
as it has different response with quota show.

Change-Id: I0a55056f0962743015fec31ce2785aaf482c184d

api-ref/source/v3/parameters.yaml

@@ -377,7 +377,7 @@ status_query:
   type: boolean
 usage:
   description: |
-    Set to ``usage=true`` to show quota usage.
+    Show project's quota usage information.
     Default is ``false``.
   in: query
   required: false
@@ -405,13 +405,6 @@ alias:
   in: body
   required: true
   type: string
-allocated:
-  description: |
-    Allocated data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 attach_mode:
   description: |
     The attach mode of attachment, read-only ('ro') or
@@ -495,6 +488,14 @@ backup_gigabytes:
   in: body
   required: true
   type: integer
+backup_gigabytes_usage:
+  description: |
+    The size (GB) usage information of backup for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 backups:
   description: |
     A list of ``backup`` objects.
@@ -507,6 +508,14 @@ backups_number:
   in: body
   required: true
   type: integer
+backups_number_usage:
+  description: |
+    The backup usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 bootable:
   description: |
     Enables or disables the bootable attribute. You
@@ -909,6 +918,23 @@ gigabytes_for_type:
   in: body
   required: true
   type: integer
+gigabytes_for_type_usage:
+  description: |
+    The size (GB) usage information of volumes and snapshots for this project
+    and this volume type, including ``in_use``, ``limit``, ``reserved`` and
+    ``allocated`` attributes. Note: ``allocated`` attribute is available only
+    when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+gigabytes_usage:
+  description: |
+    The size (GB) usage information of volumes and snapshots for this project,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 group_id_1:
   description: |
     The ID of the group.
@@ -953,6 +979,14 @@ groups_number:
   in: body
   required: true
   type: integer
+groups_number_usage:
+  description: |
+    The group usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 guaranteed_until:
   description: |
     The expire time of the message, this message could be
@@ -1066,13 +1100,6 @@ imageRef:
   in: body
   required: false
   type: string
-in_use:
-  description: |
-    The in use data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 incremental:
   description: |
     The backup mode. A valid value is ``true`` for
@@ -1134,13 +1161,6 @@ keys:
   in: body
   required: true
   type: array
-limit_usage:
-  description: |
-    The limit data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 limits:
   description: |
     A list of ``limit`` objects.
@@ -1676,6 +1696,15 @@ per_volume_gigabytes:
   in: body
   required: true
   type: integer
+per_volume_gigabytes_usage:
+  description: |
+    The size (GB) usage information for each volume, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota
+    is enabled and only ``limit`` is meaningful here.
+  in: body
+  required: true
+  type: object
 pool_name:
   description: |
     The name of the storage pool.
@@ -1808,13 +1837,6 @@ request_id:
   in: body
   required: true
   type: string
-reserved:
-  description: |
-    Reserved data size. Visible only if you set the
-    ``usage=true`` query parameter.
-  in: body
-  required: false
-  type: integer
 reserved_percentage:
   description: |
     The percentage of the total capacity that is
@@ -1957,6 +1979,22 @@ snapshots_number_for_type:
   in: body
   required: true
   type: integer
+snapshots_number_for_type_usage:
+  description: |
+    The snapshot usage information for this project and this volume type,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+snapshots_number_usage:
+  description: |
+    The snapshot usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
 source-name:
   description: |
     The resource's name.
@@ -2415,3 +2453,19 @@ volumes_number_for_type:
   in: body
   required: true
   type: integer
+volumes_number_for_type_usage:
+  description: |
+    The volume usage information for this project and this volume type,
+    including ``in_use``, ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object
+volumes_number_usage:
+  description: |
+    The volume usage information for this project, including ``in_use``,
+    ``limit``, ``reserved`` and ``allocated`` attributes.
+    Note: ``allocated`` attribute is available only when nested quota is enabled.
+  in: body
+  required: true
+  type: object

api-ref/source/v3/quota-sets.inc

@@ -47,10 +47,6 @@ Response Parameters
    - gigabytes: gigabytes
    - gigabytes_{volume_type}: gigabytes_for_type
    - backup_gigabytes: backup_gigabytes
-   - in_use: in_use
-   - reserved: reserved
-   - limit: limit_usage
-   - allocated: allocated
 
 Response Example
 ----------------
@@ -58,6 +54,55 @@ Response Example
 .. literalinclude:: ./samples/quotas-show-response.json
    :language: javascript
 
+
+Show quota usage for a project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. rest_method::  GET /v3/{admin_project_id}/os-quota-sets/{project_id}?{usage}=True
+
+Shows quota usage for a project.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: quotas_project_id
+   - admin_project_id: admin_project_id
+   - usage: usage
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - quota_set: quota_set
+   - id: project_id
+   - volumes: volumes_number_usage
+   - volumes_{volume_type}: volumes_number_for_type_usage
+   - snapshots: snapshots_number_usage
+   - snapshots_{volume_type}: snapshots_number_for_type_usage
+   - backups: backups_number_usage
+   - groups: groups_number_usage
+   - per_volume_gigabytes: per_volume_gigabytes_usage
+   - gigabytes: gigabytes_usage
+   - gigabytes_{volume_type}: gigabytes_for_type_usage
+   - backup_gigabytes: backup_gigabytes_usage
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/quotas-show-usage-response.json
+   :language: javascript
+
+
+
 Update quotas for a project
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

api-ref/source/v3/samples/quotas-show-usage-response.json

@@ -0,0 +1,65 @@
+{
+    "quota_set": {
+        "id": "a7090a26bc554d93aa845a4d41808251",
+        "volumes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "volumes_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "snapshots": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "snapshots_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "backups": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "groups": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 10,
+            "in_use": 0
+        },
+        "per_volume_gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": -1,
+            "in_use": 0
+        },
+        "gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        },
+        "gigabytes_lvmdriver-1": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        },
+        "backup_gigabytes": {
+            "reserved": 0,
+            "allocated": 0,
+            "limit": 1000,
+            "in_use": 0
+        }
+    }
+}