From faf16b20e881573ef9feb172038093b826b6c427 Mon Sep 17 00:00:00 2001
From: Atsushi SAKAI <sakaia@jp.fujitsu.com>
Date: Fri, 31 Jul 2015 22:30:09 +0900
Subject: [PATCH] Add description of specify multi-status in servers list API

Also, cleaned up descriptions for query parameters
to make these consistent.

Change-Id: Icd8a2c59dec78fe2a19ff137c5decbc4c97b1e04
Closes-Bug: #1353846
---
 .../src/wadls/compute-api/src/v2.1/common.ent | 125 +++++++-----------
 .../src/v2.1/wadl/os-server-usage-v2.1.wadl   |  10 ++
 2 files changed, 60 insertions(+), 75 deletions(-)

diff --git a/api-ref/src/wadls/compute-api/src/v2.1/common.ent b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
index 5849a851f..6d9076986 100644
--- a/api-ref/src/wadls/compute-api/src/v2.1/common.ent
+++ b/api-ref/src/wadls/compute-api/src/v2.1/common.ent
@@ -90,7 +90,7 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>A time/date stamp for when the image last changed status.</para>
+   <para>Filters the results by a specified last changed value for the image.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
@@ -98,15 +98,15 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the server in URL format.</para>
+   <para>Filters the results by a specified server name in URL format.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
-   name="name"   style="query" required="false" type="xsd:string">
+   name="name" style="query" required="false" type="xsd:string">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the image as a string.</para>
+   <para>Filters the results by a specified server name in string format.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
@@ -114,31 +114,22 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Value of the status of the image so that you can filter on "ACTIVE" for example.</para>
-</wadl:doc>
-</param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="marker" style="query" required="false" type="csapi:UUID">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>UUID of the image at which you want to set a marker.</para>
-</wadl:doc>
-</param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="limit"  style="query" required="false" type="xsd:int">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>Integer value for the limit of values to return.</para>
+   <para>
+    Filters the results by a specified image status. For example,
+    <code>ACTIVE</code>.
+  </para>
 </wadl:doc>
 </param>
+&limitMarkerReqParameter;
 <param xmlns="http://wadl.dev.java.net/2009/02"
    name="type" 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>Value of the type of image, such as BASE, SERVER, or ALL.</para>
+   <para>
+    Filters the results by a specified image type. For example,
+    <code>BASE</code>, <code>SERVER</code>, or <code>ALL</code>.
+  </para>
 </wadl:doc>
 <option value="BASE"/>
 <option value="SERVER"/>
@@ -153,8 +144,8 @@
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
    <para>
-      The name of the security group. If blank, the server is
-      created in the <code>default</code> security group.
+      The name of the security group in which the server is created. Default
+      is the <code>default</code> security group.
    </para>
 </wadl:doc>
 </param>
@@ -165,8 +156,8 @@
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
    <para>
-      You must base64-encode any configuration information or script that you
-      want to use on launch.
+      Base64-encoded configuration information or script that you want to use
+      on launch.
    </para>
 </wadl:doc>
 </param>
@@ -200,8 +191,7 @@
    <para>The image reference for the desired image
       for your server instance.
    </para>
-   <para>Specify as an ID or full
-      URL.
+   <para>Specify as an ID or full URL.
    </para>
 </wadl:doc>
 </param>
@@ -215,8 +205,7 @@
    <para>The flavor reference for the desired flavor
       for your server instance.
    </para>
-   <para>Specify as an ID or full
-      URL.
+   <para>Specify as an ID or full URL.
    </para>
 </wadl:doc>
 </param>
@@ -268,6 +257,15 @@
    xmlns:wadl="http://wadl.dev.java.net/2009/02">
     <para>The tenant ID in a multi-tenancy cloud.</para>
   </wadl:doc>
+</param>
+<param name="status" style="query" type="xsd:string"
+  xmlns="http://wadl.dev.java.net/2009/02">
+  <wadl:doc xmlns="http://docbook.org/ns/docbook"
+   xml:lang="EN"
+   xmlns:wadl="http://wadl.dev.java.net/2009/02">
+    <para>Filters the results by a specified server status. For example,
+    <code>ACTIVE</code>.</para>
+  </wadl:doc>
 </param>'>
 <!-- flavorIdRequestParameter -->
 <!ENTITY flavorIdRequestParameter '
@@ -433,8 +431,8 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>A time/date stamp for when the server
-      last changed status.
+   <para>Filters the results by a specified
+      last-changed time and date stamp value for the server.
    </para>
 </wadl:doc>
 </param>
@@ -444,7 +442,7 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the image in URL format.</para>
+   <para>Filters the results by a specified image name in URL format.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
@@ -452,40 +450,26 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the flavor in URL format.</para>
+   <para>Filters the results by a specified flavor name in URL format.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
-   name="name"   style="query" required="false" type="xsd:string">
+   name="name" style="query" required="false" type="xsd:string">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the server as a string.</para>
-</wadl:doc>
-</param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="marker" style="query" required="false" type="csapi:UUID">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>UUID of the server at which you want to set a marker.</para>
-</wadl:doc>
-</param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="limit"  style="query" required="false" type="xsd:int">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>Integer value for the limit of values to return.</para>
+   <para>Filters the results by a specified server name in string format.</para>
 </wadl:doc>
 </param>
+&limitMarkerReqParameter;
 <param xmlns="http://wadl.dev.java.net/2009/02"
    name="status" style="query" required="false" type="csapi:ServerStatus">
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Value of the status of the server so that you can filter on
-      "ACTIVE" for example.
+   <para>
+    Filters the results by a specified server status. For example,
+    <code>ACTIVE</code>.
    </para>
 </wadl:doc>
 </param>
@@ -494,7 +478,7 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Name of the host as a string.</para>
+   <para>Filters the results by a specified host name in string format.</para>
 </wadl:doc>
 </param>'>
 <!-- Servers Extended Attributes Parameters -->
@@ -504,7 +488,10 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>A time/date stamp for when the flavor last changed.</para>
+   <para>
+    Filters the results by a specified last-changed time and date stamp value
+    for the flavor.
+  </para>
 </wadl:doc>
 </param>'>
 <!ENTITY DeleteKeypairQueryParameters '
@@ -627,7 +614,10 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>A time/date stamp for when the flavor last changed.</para>
+   <para>
+    Filters the results by a specified last-changed time and date stamp value
+    for the flavor.
+   </para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
@@ -635,7 +625,7 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Integer value for the minimum disk space in GB so you can filter results.</para>
+   <para>Filters the results by a specified minimum disk space in GB.</para>
 </wadl:doc>
 </param>
 <param xmlns="http://wadl.dev.java.net/2009/02"
@@ -643,25 +633,10 @@
 <wadl:doc xmlns="http://docbook.org/ns/docbook"
    xmlns:wadl="http://wadl.dev.java.net/2009/02"
    xml:lang="EN">
-   <para>Integer value for the minimum RAM, in MB, so that you can filter results.</para>
+   <para>Filters the results by a specified minimum RAM in MB.</para>
 </wadl:doc>
 </param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="marker" style="query" required="false" type="csapi:UUID">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>UUID of the flavor at which you want to set a marker.</para>
-</wadl:doc>
-</param>
-<param xmlns="http://wadl.dev.java.net/2009/02"
-   name="limit"  style="query" required="false" type="xsd:int">
-<wadl:doc xmlns="http://docbook.org/ns/docbook"
-   xmlns:wadl="http://wadl.dev.java.net/2009/02"
-   xml:lang="EN">
-   <para>Integer value for the limit of values to return.</para>
-</wadl:doc>
-</param>'>
+&limitMarkerReqParameter;'>
 <!ENTITY flavorReqParameters '
   <param xmlns="http://wadl.dev.java.net/2009/02"
   name="disk" style="plain" required="true" type="xsd:int">
diff --git a/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
index ecb90bb41..2f32de99e 100644
--- a/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
+++ b/api-ref/src/wadls/compute-api/src/v2.1/wadl/os-server-usage-v2.1.wadl
@@ -37,7 +37,17 @@
             xmlns="http://docbook.org/ns/docbook">
             <para role="shortdesc">Lists IDs, names, and links for
                 all servers.</para>
+            <para>
+              Specify the <code>status</code> query parameters
+              to filter the results. For example:
+            </para>
+            <programlisting language="json">GET /v2.1/{tenant_id}/servers?status=ACTIVE&amp;status=ERROR</programlisting>
         </wadl:doc>
+        <request>
+            <representation mediaType="application/json">
+                &serverListParameters;
+            </representation>
+        </request>
         <response status="200">
             <representation mediaType="application/json">
                 <wadl:doc xml:lang="EN" xmlns="http://docbook.org/ns/docbook">