From 77e2d72e64f74f8334bc0ff87686fe1a7ecc9dd5 Mon Sep 17 00:00:00 2001
From: Diane Fleming <diane.fleming@rackspace.com>
Date: Fri, 20 Dec 2013 16:15:32 -0600
Subject: [PATCH] Boot volume - add imageRef and bootable attributes

To create a bootable volume, you must include imageRef and bootable attributes

Partial-Bug: #1215147

Change-Id: I31a9b40d5da0281e6ea3fcdea59ee6989a454789
author: diane fleming
---
 .../wadls/volume-api/src/v1/volume-api.wadl   |   2 +-
 .../src/v2/samples/volume_create_request.json |  19 +-
 .../src/v2/samples/volume_create_request.xml  |   6 +-
 .../v2/samples/volume_create_response.json    |  28 +-
 .../src/v2/samples/volume_create_response.xml |   8 +-
 .../wadls/volume-api/src/v2/volume-api.wadl   | 480 +++++++++++-------
 6 files changed, 320 insertions(+), 223 deletions(-)

diff --git a/api-ref/src/wadls/volume-api/src/v1/volume-api.wadl b/api-ref/src/wadls/volume-api/src/v1/volume-api.wadl
index f3badd319..e4a43481d 100644
--- a/api-ref/src/wadls/volume-api/src/v1/volume-api.wadl
+++ b/api-ref/src/wadls/volume-api/src/v1/volume-api.wadl
@@ -10,7 +10,7 @@
                 <param name="tenant_id" style="template"
                     type="csapi:UUID">
                     <doc>
-                        <p xmlns="http://www.w3.org/1999/xhtml"> The
+                        <p xmlns="http://www.w3.org/1999/xhtml">The
                             unique identifier of the tenant or
                             account. </p>
                     </doc>
diff --git a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.json b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.json
index 85fd6569d..241da399f 100644
--- a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.json
+++ b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.json
@@ -1,10 +1,13 @@
 {
-    "volume": {
-        "name": "vol-001",
-        "description": "Another volume.",
-        "size": 30,
-        "volume_type": "289da7f8-6440-407c-9fb4-7db01ec49164",
-        "availability_zone": "us-east1",
-        "metadata": {"contents": "junk"}
-     }
+   "volume":{
+      "availability_zone":"nova",
+      "bootable":"true",
+      "description":null,
+      "size":2,
+      "display_name":"my-new-vol2",
+      "imageRef":"f855b40a-66c7-4b6e-8a46-f229e70a2d0f",
+      "metadata":{
+
+      }
+   }
 }
\ No newline at end of file
diff --git a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.xml b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.xml
index 8b68197b8..b854485e4 100644
--- a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.xml
+++ b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_request.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <volume
     xmlns="http://docs.openstack.org/openstack-block-storage/2.0/content"
-    name="vol-001" description="Another volume."
-    size="30" volume_type="289da7f8-6440-407c-9fb4-7db01ec49164"
-    availability_zone="us-east-1">
+    name="vol-001" description="Another volume." size="2"
+    availability_zone="nova" bootable="true"
+    imageRef="f855b40a-66c7-4b6e-8a46-f229e70a2d0f">
     <metadata>
         <meta key="contents">junk</meta>
     </metadata>
diff --git a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.json b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.json
index 6c5da1ff2..1fbede0e9 100644
--- a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.json
+++ b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.json
@@ -1,16 +1,16 @@
 {
-    "volume": {
-        "id": "6996b558-d633-4635-8116-adf14009fcc3",
-        "links": [
-            {
-                "href": "http://localhost:8776/v2/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/6996b558-d633-4635-8116-adf14009fcc3",
-                "rel": "self"
-            },
-            {
-                "href": "http://localhost:8776/0c2eba2c5af04d3f9e9d0d410b371fde/volumes/6996b558-d633-4635-8116-adf14009fcc3",
-                "rel": "bookmark"
-            }
-        ],
-        "name": "vol-001"
-    }
+   "volume":{
+      "id":"71586f20-57de-4c06-97b9-1d1b59ed037b",
+      "links":[
+         {
+            "href":"http://23.253.72.207:8776/v2/73f0aa26640f4971864919d0eb0f0880/volumes/71586f20-57de-4c06-97b9-1d1b59ed037b",
+            "rel":"self"
+         },
+         {
+            "href":"http://23.253.72.207:8776/73f0aa26640f4971864919d0eb0f0880/volumes/71586f20-57de-4c06-97b9-1d1b59ed037b",
+            "rel":"bookmark"
+         }
+      ],
+      "name":"my-new-vol2"
+   }
 }
\ No newline at end of file
diff --git a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.xml b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.xml
index de5614d98..94ae3cea1 100644
--- a/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.xml
+++ b/api-ref/src/wadls/volume-api/src/v2/samples/volume_create_response.xml
@@ -1,9 +1,7 @@
 <?xml version='1.0' encoding='UTF-8'?>
-<volume
-    xmlns:atom="http://www.w3.org/2005/Atom"
-    xmlns="http://docs.openstack.org/api/openstack-block-storage/2.0/content"
-    name="vol-001"
-    id="6996b558-d633-4635-8116-adf14009fcc3">
+<volume xmlns:atom="http://www.w3.org/2005/Atom"
+    xmlns="http://docs.openstack.org/api/openstack-volume/2.0/content"
+    name="vol-001" id="ad63f5e4-ead6-4ca5-8c9a-461a64a40d1b">
     <attachments/>
     <metadata/>
 </volume>
diff --git a/api-ref/src/wadls/volume-api/src/v2/volume-api.wadl b/api-ref/src/wadls/volume-api/src/v2/volume-api.wadl
index 4f0d28277..7474bb0a0 100644
--- a/api-ref/src/wadls/volume-api/src/v2/volume-api.wadl
+++ b/api-ref/src/wadls/volume-api/src/v2/volume-api.wadl
@@ -5,31 +5,32 @@
 <application xmlns="http://wadl.dev.java.net/2009/02"
     xmlns:xsdxt="http://docs.rackspacecloud.com/xsd-ext/v1.0"
     xmlns:csapi="http://docs.openstack.org/api/openstack-block-storage/2.0"
+    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
     xmlns:wadl="http://wadl.dev.java.net/2009/02">
     <resources base="https://volume.example.com/">
         <resource id="version" path="v2">
             <resource id="tenant_id" path="{tenant_id}">
                 <param name="tenant_id" style="template"
-                    type="csapi:UUID">
-                    <doc>
-                        <p xmlns="http://www.w3.org/1999/xhtml">The
-                            unique identifier of the tenant or
-                            account. </p>
-                    </doc>
+                    type="xsd:string">
+                    <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                        xml:lang="EN">
+                        <para>The unique identifier of the tenant or
+                            account.</para></wadl:doc>
                 </param>
                 <resource id="volumes" path="volumes">
                     <method href="#createVolume"/>
                     <method href="#getVolumesSimple"/>
-                    <resource path="detail">
+                    <resource path="detail" id="detail">
                         <method href="#getVolumesDetail"/>
                     </resource>
-                    <resource path="{volume_id}">
+                    <resource path="{volume_id}" id="volume_id">
                         <param name="volume_id" style="template"
                             required="true" type="csapi:UUID">
-                            <doc><p
-                                   xmlns="http://www.w3.org/1999/xhtml"
-                                   >The unique identifier of an
-                                   existing volume. </p></doc>
+                            <wadl:doc
+                                xmlns="http://docbook.org/ns/docbook"
+                                xml:lang="EN"><para>The unique
+                                   identifier of an existing
+                                   volume.</para></wadl:doc>
                         </param>
                         <method href="#getVolume"/>
                         <method href="#updateVolume"/>
@@ -38,13 +39,15 @@
                 </resource>
                 <resource id="types" path="types">
                     <method href="#getVolumeTypes"/>
-                    <resource path="{volume_type_id}">
+                    <resource path="{volume_type_id}"
+                        id="volume_type_id">
                         <param name="volume_type_id" style="template"
                             required="true" type="csapi:UUID">
-                            <doc><p
-                                   xmlns="http://www.w3.org/1999/xhtml"
-                                   >The unique identifier of an
-                                   existing volume type. </p></doc>
+                            <wadl:doc
+                                xmlns="http://docbook.org/ns/docbook"
+                                xml:lang="EN"><para>The unique
+                                   identifier of an existing volume
+                                   type.</para></wadl:doc>
                         </param>
                         <method href="#getVolumeType"/>
                     </resource>
@@ -52,16 +55,17 @@
                 <resource id="snapshots" path="snapshots">
                     <method href="#createSnapshot"/>
                     <method href="#getSnapshotsSimple"/>
-                    <resource path="detail">
+                    <resource path="detail" id="detail-snapshot">
                         <method href="#getSnapshotsDetail"/>
                     </resource>
-                    <resource path="{snapshot_id}">
+                    <resource path="{snapshot_id}" id="snapshot_id">
                         <param name="snapshot_id" style="template"
                             required="true" type="csapi:UUID">
-                            <doc><p
-                                   xmlns="http://www.w3.org/1999/xhtml"
-                                   >The unique identifier of an
-                                   existing snapshot. </p></doc>
+                            <wadl:doc
+                                xmlns="http://docbook.org/ns/docbook"
+                                xml:lang="EN"><para>The unique
+                                   identifier of an existing
+                                   snapshot.</para></wadl:doc>
                         </param>
                         <method href="#getSnapshot"/>
                         <method href="#updateSnapshot"/>
@@ -72,407 +76,499 @@
         </resource>
     </resources>
     <method name="POST" id="createVolume">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Create Volume">
-            <p xmlns="http://www.w3.org/1999/xhtml">Creates a
-                volume.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Create volume">
+            <para role="shortdesc">Creates a volume.</para>
+            <para>To create a bootable volume, include the image ID
+                and set the <code>bootable</code> flag to
+                    <code>true</code> in the request body.</para>
         </wadl:doc>
         <request>
-            <!-- <param name="volume" style="plain" required="true"
-                type="csapi:string">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml"> A
-                        partial representation of a volume used in the
-                        creation process. </p></doc>
-            </param> -->
+            <param name="availability_zone" style="plain"
+                type="xsd:string" required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The availability zone.</para></wadl:doc>
+            </param>
+            <param name="bootable" style="plain" type="xsd:boolean"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>A flag that indicates whether the volume is
+                        bootable. A bootable volume is one from which
+                        you can boot an instance.</para></wadl:doc>
+            </param>
+            <param name="description" style="plain" type="xsd:string"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The volume description.</para></wadl:doc>
+            </param>
+            <param name="size" style="plain" type="xsd:int"
+                required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The size of the volume in
+                    GBs.</para></wadl:doc>
+            </param>
+            <param name="name" style="plain" type="xsd:string"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The volume name.</para></wadl:doc>
+            </param>
+            <param name="imageRef" style="plain" type="csapi:uuid"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The ID of the image from which you want to
+                        create the volume. Required to create a
+                        bootable volume.</para></wadl:doc>
+            </param>
+            <param name="metadata" style="plain" type="xsd:string"
+                required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>Metadata to associate with the
+                        volume.</para></wadl:doc>
+            </param>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_create_request.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_create_request.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </request>
         <response status="202">
+            <param name="id" style="plain" type="csapi:uuid"
+                required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The volume ID.</para></wadl:doc>
+            </param>
+            <param name="links" style="plain" type="xsd:dict"
+                required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The links through which you can access the
+                        volume.</para></wadl:doc>
+            </param>
+            <param name="name" style="plain" type="xsd:string"
+                required="true">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
+                    <para>The volume name.</para></wadl:doc>
+            </param>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_create_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_create_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getVolumesSimple">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="List Volumes">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists summary
-                information for all Cinder volumes that are accessible
-                to the tenant who submits the request. </p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="List volumes">
+            <para role="shortdesc">Lists summary information for all
+                Block Storage volumes that the tenant who submits the
+                request can access.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_list_simple_response.xml"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_list_simple_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getVolumesDetail">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="List Volumes (Detailed)">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists detailed
-                information for all Cinder volumes that are accessible
-                to the tenant who submits the request. </p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="List volumes (detailed)">
+            <para role="shortdesc">Lists detailed information for all
+                Block Storage volumes that the tenant who submits the
+                request can access.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_list_detail_response.xml"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_list_detail_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getVolume">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Show Volume Information">
-            <p xmlns="http://www.w3.org/1999/xhtml">Shows information
-                about a specified volume.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Show volume information">
+            <para role="shortdesc">Shows information about a specified
+                volume.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_show_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_show_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="PUT" id="updateVolume">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Update Volume">
-            <p xmlns="http://www.w3.org/1999/xhtml">Updates a
-                volume.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Update volume">
+            <para role="shortdesc">Updates a volume.</para>
         </wadl:doc>
         <request>
-            <param name="display_description" style="query" type="string"
-                required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">A
-                        description of the volume. </p></doc>
+            <param name="display_description" style="query"
+                type="string" required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>A description of the
+                        volume.</para></wadl:doc>
             </param>
             <param name="display_name" style="query" type="string"
                 required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">The name
-                        of the volume. </p></doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>The name of the
+                    volume.</para></wadl:doc>
             </param>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_update_request.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_update_request.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </request>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_update_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_update_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="DELETE" id="deleteVolume">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Delete Volume">
-            <p xmlns="http://www.w3.org/1999/xhtml">Deletes a
-                specified volume.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Delete volume">
+            <para role="shortdesc">Deletes a specified volume.</para>
         </wadl:doc>
         <response status="202"/>
     </method>
     <method name="GET" id="getVolumeTypes">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="List Volume Types">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists volume
-                types.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="List volume types">
+            <para role="shortdesc">Lists volume types.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_type_list_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_type_list_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getVolumeType">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Show Volume Type Information">
-            <p xmlns="http://www.w3.org/1999/xhtml">Shows information
-                about a specified volume type.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Show volume type information">
+            <para role="shortdesc">Shows information about a specified
+                volume type.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_type_show_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/volume_type_show_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="POST" id="createSnapshot">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Create Snapshot">
-            <p xmlns="http://www.w3.org/1999/xhtml"
-                >Creates a snapshot, which is a point-in-time copy of
-                a volume. You can create a new volume from the
-                snapshot.</p>
-           <!-- <p xmlns="http://www.w3.org/1999/xhtml">Before you create
-                the snapshot, you must flush all writes to the volume.
-                To flush writes, unmount any file systems on the
-                volume or detach the volume. Each time you create a
-                snapshot, you append the incremental changes for the
-                new snapshot to the previous one. The previous
-                snapshot is still available. </p>--></wadl:doc>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Create snapshot">
+            <para role="shortdesc">Creates a snapshot, which is a
+                point-in-time copy of a volume. You can create a
+                volume from the snapshot.</para>
+        </wadl:doc>
         <request>
             <param name="snapshot" style="query" type="string"
                 required="true">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">A partial
-                        representation of a snapshot used in the
-                        creation process. </p>
-                </doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>A partial representation of a
+                        snapshot used in the creation process.</para>
+                </wadl:doc>
             </param>
             <param name="volume_id" style="query" type="string"
                 required="true">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">The ID of
-                        the volume to snapshot. </p>
-                </doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>The ID of the volume to
+                        snapshot.</para>
+                </wadl:doc>
             </param>
             <param name="force" style="query" type="string"
                 required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">
-                        [True/False] Indicate whether to snapshot,
-                        even if the volume is attached.
-                        Default==False. </p>
-                </doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para> [True/False] Indicate whether
+                        to snapshot, even if the volume is attached.
+                        Default==False.</para>
+                </wadl:doc>
             </param>
             <param name="display_name" style="query" type="string"
                 required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">Name of
-                        the snapshot. Default==None. </p>
-                </doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>Name of the snapshot.
+                        Default==None.</para>
+                </wadl:doc>
             </param>
             <param name="display_description" style="query"
                 type="string" required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">
-                        Description of snapshot. Default==None. </p>
-                </doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para> Description of snapshot.
+                        Default==None.</para>
+                </wadl:doc>
             </param>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_create_request.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_create_request.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </request>
         <response status="202">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_create_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_create_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getSnapshotsSimple">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="List Snapshots">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists summary
-                information for all Cinder snapshots that are
-                accessible to the tenant who submits the request. </p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="List snapshots">
+            <para role="shortdesc">Lists summary information for all
+                Block Storage snapshots that the tenant who submits
+                the request can access.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_list_simple_response.xml"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_list_simple_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getSnapshotsDetail">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="List Snapshots (Detailed)">
-            <p xmlns="http://www.w3.org/1999/xhtml">Lists detailed
-                information for all Cinder snapshots that are
-                accessible to the tenant who submits the request. </p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="List snapshots (detailed)">
+            <para role="shortdesc">Lists detailed information for all
+                Block Storage snapshots that the tenant who submits
+                the request can access.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_list_detail_response.xml"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_list_detail_response.json"
                     />
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="GET" id="getSnapshot">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Show Snapshot">
-            <p xmlns="http://www.w3.org/1999/xhtml">Shows information
-                for a specified snapshot. </p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Show snapshot information">
+            <para role="shortdesc">Shows information for a specified
+                snapshot.</para>
         </wadl:doc>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_show_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_show_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="PUT" id="updateSnapshot">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Update Snapshot">
-            <p xmlns="http://www.w3.org/1999/xhtml">Updates a
-                specified snapshot.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Update snapshot">
+            <para role="shortdesc">Updates a specified
+                snapshot.</para>
         </wadl:doc>
         <request>
-            <param name="display_description" style="query" type="string"
-                required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">Describes
-                        the snapshot. </p></doc>
+            <param name="display_description" style="query"
+                type="string" required="false">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>Describes the
+                    snapshot.</para></wadl:doc>
             </param>
             <param name="display_name" style="query" type="string"
                 required="false">
-                <doc><p xmlns="http://www.w3.org/1999/xhtml">The name
-                        of the snapshot. </p></doc>
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN"><para>The name of the
+                        snapshot.</para></wadl:doc>
             </param>
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_update_request.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_update_request.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </request>
         <response status="200">
             <representation mediaType="application/xml">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_update_response.xml"/>
-                </doc>
+                </wadl:doc>
             </representation>
             <representation mediaType="application/json">
-                <doc xml:lang="EN">
+                <wadl:doc xmlns="http://docbook.org/ns/docbook"
+                    xml:lang="EN">
                     <xsdxt:code
                         href="samples/snapshot_update_response.json"/>
-                </doc>
+                </wadl:doc>
             </representation>
         </response>
     </method>
     <method name="DELETE" id="deleteSnapshot">
-        <wadl:doc xmlns="http://www.w3.org/1999/xhtml" xml:lang="EN"
-            title="Delete Snapshot">
-            <p xmlns="http://www.w3.org/1999/xhtml">Deletes a
-                specified snapshot.</p>
+        <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
+            title="Delete snapshot">
+            <para role="shortdesc">Deletes a specified
+                snapshot.</para>
         </wadl:doc>
         <response status="202"/>
     </method>