api-ref: Improve sort, pagination parameter docs

The various index APIs (e.g. 'GET /volumes') support two forms of sort
parameter: the legacy 'sort_key'/'sort_dir' parameters and the combined
'sort' parameter. We were documenting different parameters in different
APIs despite the fact all APIs support all parameters.

In a similar vein, the various index APIs support the same three
pagination parameters: 'offset', 'limit', and 'marker'. Once again, we
were documenting these inconsistently.

Correct both issues.

Change-Id: Ia3300a8852825f7da830f7b1ed37b27625e267e9
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>

api-ref/source/v3/attachments.inc

@@ -161,6 +161,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker
@@ -216,6 +218,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

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

@@ -38,7 +38,10 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
+   - offset: offset
    - marker: marker
 
 
@@ -248,7 +251,10 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
+   - offset: offset
    - marker: marker
 
 

api-ref/source/v3/ext-backups.inc

@@ -65,6 +65,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker
@@ -405,7 +407,10 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
+   - offset: offset
    - marker: marker
    - with_count: with_count
 

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

@@ -116,6 +116,7 @@ Request
 
    - project_id: project_id_path
    - all_tenants: all-tenants
+   - sort: sort_group_snapshot
    - sort_key: sort_key_group_snapshot
    - sort_dir: sort_dir_group_snapshot
    - limit: limit_group_snapshot
@@ -172,6 +173,7 @@ Request
 
    - project_id: project_id_path
    - all_tenants: all-tenants
+   - sort: sort_group_snapshot
    - sort_key: sort_key_group_snapshot
    - sort_dir: sort_dir_group_snapshot
    - limit: limit_group_snapshot

api-ref/source/v3/group-types.inc

@@ -213,6 +213,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

api-ref/source/v3/groups.inc

@@ -45,6 +45,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker
@@ -294,6 +296,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

api-ref/source/v3/messages.inc

@@ -119,6 +119,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

api-ref/source/v3/parameters.yaml

@@ -468,8 +468,8 @@ service_binary_query:
 sort:
   description: |
     Comma-separated list of sort keys and optional
-    sort directions in the form of < key > [: < direction > ]. A valid
+    sort directions in the form of ``< key > [: < direction > ]``.
-    direction is ``asc`` (ascending) or ``desc`` (descending).
+    A valid direction is ``asc`` (ascending) or ``desc`` (descending).
   in: query
   required: false
   type: string
@@ -478,6 +478,7 @@ sort_dir:
     Sorts by one or more sets of attribute and sort
     direction combinations. If you omit the sort direction in a set,
     default is ``desc``.
+    Deprecated in favour of the combined ``sort`` parameter.
   in: query
   required: false
   type: string
@@ -486,6 +487,7 @@ sort_dir_group_snapshot:
     Sorts by one or more sets of attribute and sort
     direction combinations. If you omit the sort direction in a set,
     default is ``desc``.
+    Deprecated in favour of the combined ``sort`` parameter.
   in: query
   required: false
   type: string
@@ -495,10 +497,20 @@ sort_dir_transfer:
     Sorts by one or more sets of attribute and sort
     direction combinations. If you omit the sort direction in a set,
     default is ``desc``.
+    Deprecated in favour of the combined ``sort`` parameter.
   in: query
   required: false
   type: string
   min_version: 3.59
+sort_group_snapshot:
+  description: |
+    Comma-separated list of sort keys and optional
+    sort directions in the form of ``< key > [: < direction > ]``.
+    A valid direction is ``asc`` (ascending) or ``desc`` (descending).
+  in: query
+  required: false
+  type: string
+  min_version: 3.29
 sort_key:
   description: |
     Sorts by an attribute. A valid value is ``name``,
@@ -506,6 +518,7 @@ sort_key:
     ``id``, ``created_at``, or ``updated_at``. Default is
     ``created_at``. The API uses the natural sorting direction of the
     ``sort_key`` attribute value.
+    Deprecated in favour of the combined ``sort`` parameter.
   in: query
   required: false
   type: string
@@ -516,6 +529,7 @@ sort_key_group_snapshot:
     ``id``, ``created_at``, or ``updated_at``. Default is
     ``created_at``. The API uses the natural sorting direction of the
     ``sort_key`` attribute value.
+    Deprecated in favour of the combined ``sort`` parameter.
   in: query
   required: false
   type: string
@@ -525,6 +539,16 @@ sort_key_transfer:
     Sorts by an attribute. Default is
     ``created_at``. The API uses the natural sorting direction of the
     ``sort_key`` attribute value.
+    Deprecated in favour of the combined ``sort`` parameter.
+  in: query
+  required: false
+  type: string
+  min_version: 3.59
+sort_transfer:
+  description: |
+    Comma-separated list of sort keys and optional
+    sort directions in the form of ``< key > [: < direction > ]``.
+    A valid direction is ``asc`` (ascending) or ``desc`` (descending).
   in: query
   required: false
   type: string

api-ref/source/v3/qos-specs-v3-qos-specs.inc

@@ -365,7 +365,10 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
+   - offset: offset
    - marker: marker
 
 

api-ref/source/v3/snapshot-manage.inc

@@ -99,6 +99,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - offset: offset
    - limit: limit
    - marker: marker
@@ -150,6 +152,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - offset: offset
    - limit: limit
    - marker: marker

api-ref/source/v3/vol-transfer-v3.inc

@@ -148,11 +148,12 @@ Request
 
    - project_id: project_id_path
    - all_tenants: all-tenants
+   - sort: sort_transfer
+   - sort_key: sort_key_transfer
+   - sort_dir: sort_dir_transfer
    - limit: limit_transfer
    - offset: offset_transfer
    - marker: marker_transfer
-   - sort_key: sort_key_transfer
-   - sort_dir: sort_dir_transfer
 
 
 Response Parameters

api-ref/source/v3/volume-manage.inc

@@ -123,6 +123,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - offset: offset
    - limit: limit
    - marker: marker
@@ -172,6 +174,8 @@ Request
 
    - project_id: project_id_path
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - offset: offset
    - limit: limit
    - marker: marker

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

@@ -63,6 +63,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker
@@ -195,6 +197,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

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

@@ -440,6 +440,8 @@ Request
    - project_id: project_id_path
    - is_public: is_public_volume_type_query
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker

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

@@ -92,6 +92,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker
@@ -308,6 +310,8 @@ Request
    - project_id: project_id_path
    - all_tenants: all-tenants
    - sort: sort
+   - sort_key: sort_key
+   - sort_dir: sort_dir
    - limit: limit
    - offset: offset
    - marker: marker