openstack
/
trove-integration
Code Issues Proposed changes

Fix WADL validation errors 

The dbaas.wadl file contains many text blocks which need to be
wrapped in <para> tags. Newer versions of clouddocs-maven-plugin
validate these blocks, resulting in docs build errors until they are
fixed.

Co-Authored-By: Nikhil Manchanda <SlickNik@gmail.com>

Change-Id: Ia5733a7fb1c0827a7cec500e1ee51a896a0e7754
This commit is contained in:
Sam Harwell 2013-11-25 10:28:37 -06:00 committed by Nikhil Manchanda
parent b7754c4402
commit ea12be0eea
1 changed files with 33 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
xsd/dbaas.wadl
View File

@ -31,7 +31,7 @@
<resource id="instances" path="instances">
<method href="#createInstance" />
<method href="#getInstance" />
<resource id="instanceId" path="{instanceId}">
<param name="instanceId" style="template"
type="xsd:string" >
@ -71,7 +71,7 @@
</resource>
<resource id="flavors" path="flavors">
<method href="#getFlavors" />
<resource id="flavorId" path="{flavorId}">
<param name="flavorId" style="template" type="xsd:string" >
<doc>The flavor ID for the specified flavor.</doc></param>
@ -176,9 +176,9 @@
<listitem>
<para>The default binding for the MySQL instance is port 3306.</para>
</listitem>
<listitem>
Database instances are directly accessible only on the internal ServiceNet network and using a Cloud resource within the same regional datacenter. For example, a database instance in DFW can only be accessed by a Cloud Server in DFW. For details and information about using a public Cloud Load Balancer to allow access to your database instance, refer to
<xref linkend="Accessibility"/> for details.
<listitem>
<para>Database instances are directly accessible only on the internal ServiceNet network and using a Cloud resource within the same regional datacenter. For example, a database instance in DFW can only be accessed by a Cloud Server in DFW. For details and information about using a public Cloud Load Balancer to allow access to your database instance, refer to
<xref linkend="Accessibility"/> for details.</para>
</listitem>
</itemizedlist></note>
<para>The following table lists the required and optional attributes for Create Instance:</para>
@ -196,10 +196,10 @@
<tr>
<td colspan="1" rowspan="3">Instance</td>
<td colspan="1">flavorRef</td>
<td colspan="3"><para>Reference (href) to a flavor as specified in the response from the List Flavors API call.
<td colspan="3"><para>Reference (href) to a flavor as specified in the response from the List Flavors API call.
This is the actual URI as specified by the href field in the link. For example, in the following List Flavors response, the link to flavor id 1 is specified as
"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1".</para>
<note>Rather than the flavor URI, you can also pass the flavor id (integer) as the value for flavorRef. For example, the flavor id for the flavor URI shown above is "1".</note>
<note><para>Rather than the flavor URI, you can also pass the flavor id (integer) as the value for flavorRef. For example, the flavor id for the flavor URI shown above is "1".</para></note>
<para>Refer to <xref linkend="GET_getFlavors__version___accountId__flavors_"/> for details.</para></td>
<td colspan="1">Yes</td>
</tr>
@ -290,9 +290,9 @@
<para role="shortdesc">Deletes the specified database instance.</para>
<para>This operation deletes the specified database instance, including any associated data.</para>
<para>Refer to <xref linkend="database_instance_status"/> for a list of possible database instance statuses that may be returned.</para>
<note>This operation does not delete any read slaves.</note>
<note><para>This operation does not delete any read slaves.</para></note>
<remark>Reviewer: please provide a description of read slaves that I can add to the previous note.</remark>
<note>This operation is not allowed when the instance state is either <code>REBUILDING</code> or <code>BUILDING</code>.</note>
<note><para>This operation is not allowed when the instance state is either <code>REBUILDING</code> or <code>BUILDING</code>.</para></note>
</wadl:doc>
<request>
<representation mediaType="application/xml">
@ -335,7 +335,7 @@
<representation mediaType="application/xml">
<doc>
<para xmlns="http://docbook.org/ns/docbook">The following examples show the List All Database Instances Detail requests:</para>
<xsdxt:code href="../apidocs/src/resources/samples/db-instances-index-request.xml"/>
</doc>
</representation>
@ -349,7 +349,7 @@
<representation mediaType="application/xml" >
<doc>
<para xmlns="http://docbook.org/ns/docbook">The following examples show the List All Database Instances responses:</para>
<xsdxt:code href="../apidocs/src/resources/samples/db-instances-index-response.xml"/>
</doc>
</representation>
@ -369,10 +369,10 @@
<para role="shortdesc">Lists status and details for a specified database instance.</para>
<para>This operation lists the status and details of the specified database instance.</para>
<para>This operation lists the volume size in gigabytes (GB) and the approximate GB used.</para>
<note>After instance creation, the <code>used</code> size of your volume will be
<note><para>After instance creation, the <code>used</code> size of your volume will be
greater than 0. This is expected and due to the automatic creation of
non-empty transaction logs for mysql optimization. The <code>used</code> attribute is <emphasis>not</emphasis> returned
in the response when the status for the instance is BUILD, REBOOT, or RESIZE. </note>
non-empty transaction logs for mysql optimization. The <code>used</code> attribute is <emphasis>not</emphasis> returned
in the response when the status for the instance is BUILD, REBOOT, or RESIZE.</para></note>
<para>Refer to <xref linkend="database_instance_status"/> for a list of possible database instance statuses that may be returned.</para>
<para>The list operations return a DNS-resolvable hostname associated with the database instance instead of an IP address. Since the hostname always resolves to the correct IP address of the database instance, this relieves the user from the task of maintaining the mapping. Note that although the IP address may likely change on resizing, migrating, and so forth, the hostname always resolves to the correct database instance.</para>
</wadl:doc>
@ -387,7 +387,7 @@
<doc>
<xsdxt:code href="../apidocs/src/resources/samples/db-instance-status-detail-request.xml"/>
</doc>
</representation>
</representation>
</request>
<response status="200">
<representation mediaType="application/xml"
@ -413,7 +413,7 @@
<wadl:doc xml:lang="EN" title="Restart Instance" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Restart the database service on the instance.</para>
<para>The restart operation will restart only the MySQL Instance. Restarting MySQL will erase any dynamic configuration settings that you have made within MySQL.</para>
<note>The MySQL service will be unavailable until the instance restarts.</note>
<note><para>The MySQL service will be unavailable until the instance restarts.</para></note>
<para>This operation returns a 202 Accepted response.</para>
</wadl:doc>
<request>
@ -490,7 +490,7 @@
<para role="shortdesc">Resize the <glossterm>volume</glossterm> attached to the Instance.</para>
<para>This operation supports resizing the attached volume for an instance. It supports only increasing the volume size and does not support decreasing the size.
The volume size is in gigabytes (GB) and must be an integer.</para>
<note>You cannot increase the volume to a size larger than the API volume size limit specifies.</note>
<note><para>You cannot increase the volume to a size larger than the API volume size limit specifies.</para></note>
<para>This operation returns a 202 Accepted response.</para>
</wadl:doc>
<request>
@ -565,9 +565,9 @@
<para>See the MySQL documentation for information about supported character sets and collations at <link
xlink:href="http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html"
>http://dev.mysql.com/doc/refman/5.1/en/charset-mysql.html</link>.</para>
<note>The following database names are reserved and cannot be used for creating databases: lost+found, information_schema, and mysql.</note>
<note><para>The following database names are reserved and cannot be used for creating databases: lost+found, information_schema, and mysql.</para></note>
<para>Refer to the following tables for information about characters that are valid/invalid for creating database names.</para>
<table rules="all" width="40%">
@ -670,7 +670,7 @@
<doc>
<xsdxt:code href="../apidocs/src/resources/samples/db-create-databases-response.json"/>
</doc>
</representation>
</representation>
</response>
&commonFaults;
&getFaults;
@ -681,7 +681,7 @@
<wadl:doc xml:lang="EN" title="List Databases for Instance" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Lists databases for the specified instance.</para>
<para>This operation lists the databases for the specified instance.</para>
<note>This operation returns only the user-defined databases, not the system databases. The system databases (mysql, information_schema, lost+found) can only be viewed by a database administrator.</note>
<note><para>This operation returns only the user-defined databases, not the system databases. The system databases (mysql, information_schema, lost+found) can only be viewed by a database administrator.</para></note>
</wadl:doc>
<request>
<representation mediaType="application/xml">
@ -759,10 +759,10 @@
<para>If the corresponding request cannot be fulfilled due to insufficient or invalid data, an HTTP 400 "Bad Request" error response is returned with information regarding the nature of the failure. Failures in the validation process are non-recoverable and require the caller to correct the cause of the failure and POST the request again.</para>
<para>The following table lists the required attributes for Create User. Refer to the request examples for the required xml/json format:</para>
<table rules="all" width="500">
<caption>Required Attributes for Create User</caption>
<thead>
<tr>
<td colspan="1">Applies To</td>
@ -792,7 +792,7 @@
</tr>
</tbody>
</table>
<note><title>Notes</title><itemizedlist>
<listitem>
<para>A user is granted all privileges on the specified databases.</para>
@ -924,7 +924,7 @@
<wadl:doc xml:lang="EN" title="List Users in Database Instance" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Lists the users in the specified database instance.</para>
<para>This operation lists the users in the specified database instance, along with the associated databases for that user. </para>
<note>This operation does not return the system users (database administrators that administer the health of the database). Also, this operation returns the "root" user only if "root" user has been enabled.</note>
<note><para>This operation does not return the system users (database administrators that administer the health of the database). Also, this operation returns the "root" user only if "root" user has been enabled.</para></note>
<para>The following notes apply to MySQL users:</para>
<itemizedlist spacing="compact">
@ -978,11 +978,11 @@
<wadl:doc xml:lang="EN" title="Delete User" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Deletes the user identified by {name} for the specified database instance.</para>
<para>This operation deletes the specified user for the specified database instance.</para>
<warning>There is a bug in a python library that Rackspace is using that may cause incorrect user deletions to occur
if a period (.) is used in the user name. In this case, the user name is truncated to remove the portion of the
name from the period to the end, leaving only the portion from the beginning up to the period. For example, for a
user named "my.userA", the bug would truncate the user name to "my", and if the user "my" exists, that user will
be incorrectly deleted. To avoid the problem, do not use periods in user names.</warning>
<warning><para>There is a bug in a python library that Rackspace is using that may cause incorrect user deletions to occur
if a period (.) is used in the user name. In this case, the user name is truncated to remove the portion of the
name from the period to the end, leaving only the portion from the beginning up to the period. For example, for a
user named "my.userA", the bug would truncate the user name to "my", and if the user "my" exists, that user will
be incorrectly deleted. To avoid the problem, do not use periods in user names.</para></warning>
</wadl:doc>
<request>
<representation mediaType="application/xml">
@ -1019,7 +1019,7 @@
<wadl:doc xml:lang="EN" title="Enable Root User" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Enables the root user for the specified database instance and returns the root password.</para>
<para>This operation enables login from any host for the root user and provides the user with a generated root password.</para>
<note>Changes you make as a root user may cause detrimental effects to the database instance and unpredictable behavior for API operations. When you enable the root user, you accept the possibility that we will not be able to support your database instance. While enabling root does not prevent us from a “best effort” approach to helping you if something goes wrong with your instance, we cannot ensure that we will be able to assist you if you change core MySQL settings. These changes can be (but are not limited to) turning off binlogs, removing users that we use to access your instance, and so forth.</note>
<note><para>Changes you make as a root user may cause detrimental effects to the database instance and unpredictable behavior for API operations. When you enable the root user, you accept the possibility that we will not be able to support your database instance. While enabling root does not prevent us from a “best effort” approach to helping you if something goes wrong with your instance, we cannot ensure that we will be able to assist you if you change core MySQL settings. These changes can be (but are not limited to) turning off binlogs, removing users that we use to access your instance, and so forth.</para></note>
</wadl:doc>
<request>
<representation mediaType="application/xml">
@ -1132,14 +1132,14 @@
&getFaults;
</method>
<method name="GET" id="getFlavorById">
<wadl:doc xml:lang="EN" title="List Flavor By ID" xmlns="http://docbook.org/ns/docbook">
<para role="shortdesc">Lists all flavor information about the specified flavor ID.</para>
<para>This operation lists all information for the specified flavor ID with details of the RAM.</para>
<para>This resource is identical to the flavors found in the OpenStack Nova API, but without the disk property.</para>
<note>The flavorId parameter should be an integer. If a floating point value is used for the flavorId parameter, the decimal portion is truncated and the integer portion is used as the value of the flavorId.</note>
<note><para>The flavorId parameter should be an integer. If a floating point value is used for the flavorId parameter, the decimal portion is truncated and the integer portion is used as the value of the flavorId.</para></note>
<remark>Writer: need to confirm that this behavior is not changed in subsequent releases, and if it is prevented, remove the Note above.</remark>
</wadl:doc>
<request>