From f9badcd66e41750adc35f2add249cdede6c79dbb Mon Sep 17 00:00:00 2001
From: Hongbin Lu <hongbin.lu@huawei.com>
Date: Wed, 11 Apr 2018 20:38:10 +0000
Subject: [PATCH] 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 | 48 +++++++++++++++++++++++++++++++
 api-ref/source/v2/ports.inc       |  2 ++
 api-ref/source/v2/segments.inc    |  2 ++
 api-ref/source/v2/trunk.inc       |  2 ++
 4 files changed, 54 insertions(+)

diff --git a/api-ref/source/v2/parameters.yaml b/api-ref/source/v2/parameters.yaml
index bc2aa5a2d..64ea168f3 100644
--- a/api-ref/source/v2/parameters.yaml
+++ b/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
diff --git a/api-ref/source/v2/ports.inc b/api-ref/source/v2/ports.inc
index 489306b32..edfabff32 100644
--- a/api-ref/source/v2/ports.inc
+++ b/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
diff --git a/api-ref/source/v2/segments.inc b/api-ref/source/v2/segments.inc
index e626c78d3..0e928f694 100644
--- a/api-ref/source/v2/segments.inc
+++ b/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
diff --git a/api-ref/source/v2/trunk.inc b/api-ref/source/v2/trunk.inc
index fb9844219..b388e08d8 100644
--- a/api-ref/source/v2/trunk.inc
+++ b/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