api-ref: document sorting parameters for l2

API users can use the 'sort_key' and 'sort_dir' to do the sorting
on list result. This patch add documentation of these two parameters
for l2 networking resources, including port, segment, and trunk.

Depends-On: I325396bb0256196ee6c6fc42cc812a0c75ae3827
Change-Id: I7f3b9811c8b72dfbee87335ff0a56fae3148c366
Partial-Bug: #1749024

api-ref/source/v2/parameters.yaml

@@ -610,6 +610,25 @@ not-tags-query:
   in: query
   required: false
   type: string
+port-sort_key:
+  description: |
+    Sorts by a port attribute. You can specify multiple pairs of sort key
+    and sort direction query parameters. The sort keys are limited to:
+
+    - ``admin_state_up``
+    - ``device_id``
+    - ``device_owner``
+    - ``id``
+    - ``ip_allocation``
+    - ``mac_address``
+    - ``name``
+    - ``network_id``
+    - ``project_id``
+    - ``status``
+    - ``tenant_id``
+  in: query
+  required: false
+  type: string
 port-status-query:
   description: |
     Filter the port list result by the port status.
@@ -788,6 +807,20 @@ security_group_rule-sort_key:
   in: query
   required: false
   type: string
+segment-sort_key:
+  description: |
+    Sorts by a segment attribute. You can specify multiple pairs of sort key
+    and sort direction query parameters. The sort keys are limited to:
+
+    - ``id``
+    - ``name``
+    - ``network_id``
+    - ``network_type``
+    - ``physical_network``
+    - ``segmentation_id``
+  in: query
+  required: false
+  type: string
 shared-query:
   description: |
     Admin-only. Filter the list result based on whether the resource is
@@ -922,6 +955,21 @@ tags-query:
   in: query
   required: false
   type: string
+trunk-sort_key:
+  description: |
+    Sorts by a trunk attribute. You can specify multiple pairs of sort key
+    and sort direction query parameters. The sort keys are limited to:
+
+    - ``admin_state_up``
+    - ``id``
+    - ``name``
+    - ``port_id``
+    - ``project_id``
+    - ``status``
+    - ``tenant_id``
+  in: query
+  required: false
+  type: string
 trunk-status-query:
   description: |
     Filter the trunk list result by the status for the trunk. Possible values

api-ref/source/v2/ports.inc

@@ -349,6 +349,8 @@ Request
    - network_id: network_id-query
    - project_id: project_id-query
    - revision_number: revision_number-query
+   - sort_dir: sort_dir
+   - sort_key: port-sort_key
    - status: port-status-query
    - tenant_id: project_id-query
    - tags: tags-query

api-ref/source/v2/segments.inc

@@ -149,6 +149,8 @@ Request
    - segmentation_id: provider:segmentation_id-query
    - name: name-query
    - description: description-query
+   - sort_dir: sort_dir
+   - sort_key: segment-sort_key
    - fields: fields
 
 Response Parameters

api-ref/source/v2/trunk.inc

@@ -56,6 +56,8 @@ Request Parameters
    - status: trunk-status-query
    - tenant_id: project_id-query
    - project_id: project_id-query
+   - sort_dir: sort_dir
+   - sort_key: trunk-sort_key
    - tags: tags-query
    - tags-any: tags-any-query
    - not-tags: not-tags-query