api-ref: document sorting parameters for networks

API users can use the 'sort_key' and 'sort_dir' to do the sorting
on list result. This patch improves the documentation of these two
sorting parameters.

In particular, we explicitly list all the attributes that can be used
as a sort_key for network resource. This is necessary because the list
of sort_key varies across different resources and it is hard for
API users to guess which resource support which sort_key.

Change-Id: I5183bfe4c835dae0f0bfae61114e9b9be2877b0f

api-ref/source/v2/networks.inc

@@ -358,6 +358,8 @@ Request
    - tags-any: tags-any-query
    - not-tags: not-tags-query
    - not-tags-any: not-tags-any-query
+   - sort_dir: sort_dir
+   - sort_key: network-sort_key
    - fields: fields
 
 Response Parameters

api-ref/source/v2/parameters.yaml

@@ -544,6 +544,21 @@ network-shared-query:
   in: query
   required: false
   type: boolean
+network-sort_key:
+  description: |
+    Sorts by a network attribute. You can specify multiple pairs of sort key
+    and sort direction query parameters. The sort keys are limited to:
+
+    - ``admin_state_up``
+    - ``availability_zone_hints``
+    - ``id``
+    - ``mtu``
+    - ``name``
+    - ``status``
+    - ``tenant_id``
+  in: query
+  required: false
+  type: string
 network-status-query:
   description: |
     Filter the network list result by network status. Values are ``ACTIVE``,
@@ -709,6 +724,14 @@ shared-query:
   in: query
   required: false
   type: boolean
+sort_dir:
+  description: |
+    Sort direction. A valid value is ``asc`` (ascending) or ``desc``
+    (descending). You can specify multiple pairs of sort key and
+    sort direction query parameters.
+  in: query
+  required: false
+  type: string
 subnet-enable_dhcp-query:
   description: |
     Filter the subnet list result based on if is enabled or disabled