From be7b20ba836196f378d450556a09b7585d09d6af Mon Sep 17 00:00:00 2001
From: Atsushi SAKAI <sakaia@jp.fujitsu.com>
Date: Tue, 4 Aug 2015 22:01:14 +0900
Subject: [PATCH] Update image sort flag documentation

  multiple sort_key 1405184
  sort dir each key 1431682
  new syntax sort   1431756

Change-Id: I81f4114f801f779bc80cfe592e979eaf91aec645
Closes-Bug: #1405184
Closes-Bug: #1431682
Closes-Bug: #1431756
---
 api-ref/src/wadls/image-api/src/v2/common.ent | 32 +++++++++++++-----
 .../wadls/image-api/src/v2/os-image-v2.wadl   | 33 +++++++++++++++----
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/api-ref/src/wadls/image-api/src/v2/common.ent b/api-ref/src/wadls/image-api/src/v2/common.ent
index 276a1c17b..4a77ec2d2 100644
--- a/api-ref/src/wadls/image-api/src/v2/common.ent
+++ b/api-ref/src/wadls/image-api/src/v2/common.ent
@@ -164,12 +164,13 @@
    style="query" required="false" type="xsd:string" default="ALL">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
-   <para>Sort key. Results will be sorted by the requested image
-      attribute.  Accepted values are <code>name</code>,
-      <code>status</code>, <code>container_format</code>,
-      <code>disk_format</code>, <code>size</code>,
-      <code>id</code>, <code>created_at</code>, and
-      <code>updated_at</code>.  Default is <code>created_at</code>.
+   <para>
+      Sorts by the requested image attribute. Accepted values are
+      <code>name</code>, <code>status</code>, <code>container_format</code>,
+      <code>disk_format</code>, <code>size</code>, <code>id</code>,
+      <code>created_at</code>, and <code>updated_at</code>. Default is
+      <code>created_at</code>. The API uses the natural sorting direction of
+      the image attribute that is provided as the <code>sort_key</code>.
    </para>
 </wadl:doc>
 </param>
@@ -178,11 +179,26 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
    <para>
-      Sort direction. A valid value is <code>asc</code> (ascending) or
-      <code>desc</code> (descending). Default is <code>desc</code>.
+      Sorts by one or more sets of attribute and sort direction combinations.
+      If you omit the sort direction in a set, default is <code>desc</code>.
    </para>
 </wadl:doc>
 </param>
+<param xmlns="http://wadl.dev.java.net/2009/02" name="sort"
+   style="query" required="false" type="xsd:string" default="ALL">
+<wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02" xml:lang="EN">
+   <para>
+
+      Sorts by one or more attribute and sort direction combinations. You can
+      also set multiple sort keys and directions. Default direction is
+      <code>desc</code>.
+
+   </para>
+   <para>For example:</para>
+    <programlisting language="json">GET /v2/images?sort=name:asc,status:desc</programlisting>
+</wadl:doc>
+</param>
 <param xmlns="http://wadl.dev.java.net/2009/02" name="tag"
    style="query" required="false" type="xsd:string" default="ALL">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
diff --git a/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl b/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl
index 0930319a8..aceda0c73 100644
--- a/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl
+++ b/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl
@@ -148,16 +148,37 @@
             filters the container to include only images that are
             between 1 and 4 MB.
          </para>
-         <para>You can sort the results of this operation by using
-            the <code>sort_key</code> and <code>sort_dir</code>
-            parameters. The API uses the natural sorting of
-            whatever image attribute is provided as the
-            <code>sort_key</code>.
-         </para>
          <para>You can see a list of VM images which status is in
             <code>active</code>, <code>queued</code>, or
             <code>saving</code>.
          </para>
+         <para>
+            You can use query parameters to sort the results of this operation.
+         </para>
+         <itemizedlist>
+            <listitem>
+               <para>
+                  <code>sort_key</code>. Sorts by the requested image
+                  attribute. Sorts in the natural sorting direction of the image attribute that
+                  is provided as the <code>sort_key</code>.
+               </para>
+            </listitem>
+            <listitem><para><code>sort_dir</code>. Sorts in a specified sort direction.</para></listitem>
+            <listitem>
+               <para>
+                  <code>sort</code>. Sorts by one or more sets of attribute
+                  and sort direction combinations. If you omit the sort direction in a set,
+                  default is <code>desc</code>.
+               </para>
+            </listitem>
+         </itemizedlist>
+         <para>To specify the <code>sort_key</code> and
+            <code>sort_dir</code> query parameters to sort the results:
+         </para>
+            <programlisting language="json">GET /v2/images?sort_key=name&amp;sort_dir=asc&amp;sort_key=status&amp;sort_dir=desc</programlisting>
+         <para>To specify the <code>sort</code> query parameter to sort the results:
+         </para>
+            <programlisting language="json">GET /v2/images?sort=name:asc,status:desc</programlisting>
       </wadl:doc>
       <request>
          <representation mediaType="application/json">