Open Stack

Copying the list so others may look up the answer later.

On Wed, Dec 3, 2014 at 10:26 AM, Waines, Greg <Greg.Waines at windriver.com>
wrote:

>  Anne / Andreas,
>
>
>
> First … I apologize for using your personal emails rather than the mailing
> list, but I dropped off the
> mailing list a month or so ago because most of the emails did not apply to
> what I was up to.
>
>
>
> Anyways, what I wanted to ask you …
>
> So I basically cloned the REST API DOC structure that you guys have … i.e.
> using the maven tool
> and the same directory layout etc … in order to support the writing of
> ‘Incremental REST API Docs’
> for extensions that we are doing on top of OpenStack.
>
>
>
> A somewhat minor (but annoying) behavior that I’ve noticed in the PDF
> output is:
>

Wanted to point out that there are two PDF outputs, one for the API
Reference, one for the longer "Developer Guides." It looks like you're
talking about the longer "Developer Guide" which we do not produce for
OpenStack any more for various reasons I don't need to go into to answer
your question. Just wanted to be sure you have some context.

>  ·         for both Request and Response sections
>
> ·         even though I define a Table for the request/response
> parameters and
> provide a JSON example
>
> ·         …
>
> ·
> *I always get the line      “This operation does not accept a request
> body.”*
>

This line is found in the xsl transforms that are in
clouddocs-maven-plugin.
https://github.com/stackforge/clouddocs-maven-plugin/blob/a0c4efad86d03d263bb6d02977d088f8a9ee5eb0/src/main/resources/cloud/apipage/apipage-main.xsl#L29
https://github.com/stackforge/clouddocs-maven-plugin/blob/adff7d1c8018e6e4d3dc249f7210d99836584342/src/main/resources/cloud/process-embedded-wadl-3.xsl#L17

>  ·         see below
>
> o   I’ve cut & paste a section from the PDF
>
> o   and provided the applicable portion of the WADL file
>
> ·
>
> ·         NOTE
>
> o   in order to reduce the size of the overall document,
> I was only providing ‘samples’ for JSON … and NOT XML
>
>
>

OpenStack APIs are moving away from XML requests and responses as well.


>  Any ideas how I can get rid of the incorrect statement above ?
> (when I actually have specified a request body)
>
>
>

Those PDFs are riddled with these types of issues. You can certainly edit
the message itself in the maven plugin and rebuild it. Or you could figure
out the logic where the maven plugin assumes the presence of an XML request
and fix that. In the OpenStack docs we don't intend to use this output
going forward.

Hope this helps -
Anne


>  Greg.
>
>
>
>
>
>
>
>
>
>
>
>
>
> … excerpt from the WADL file:
>
>
>
>     <method name="PATCH" id="modifyHost">
>
>         <wadl:doc xmlns="http://docbook.org/ns/docbook" xml:lang="EN"
>
>             title="Modify host">
>
>             <para role="shortdesc">Modifies a specific host.</para>
>
>             <para>The atrributes of a Host which are modifiable:</para>
>
>             <itemizedlist>
>
>                 <listitem><para>personality,</para></listitem>
>
>                 <listitem><para>hostname,</para></listitem>
>
>                 <listitem><para>bm_type,</para></listitem>
>
>                 <listitem><para>bm_mac,</para></listitem>
>
>                 <listitem><para>bm_username,</para></listitem>
>
>                 <listitem><para>serialid,</para></listitem>
>
>                 <listitem><para>location.</para></listitem>
>
>             </itemizedlist>
>
>         </wadl:doc>
>
>         <request>
>
>             <representation mediaType="application/xml">
>
>                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
> xml:lang="EN">
>
>                 </wadl:doc>
>
>                 <param xmlns="http://wadl.dev.java.net/2009/02"
>
>                     name="firstParameter" style="plain" type="xsd:string" >
>
>                     <wadl:doc xmlns="http://docbook.org/ns/docbook"
>
>                         xmlns:wadl="http://wadl.dev.java.net/2009/02"
> xml:lang="EN">
>
>                         <para>This parameter specifies ... .
>
>                             Valid values are:  <code>value1</code>,
> <code>value2</code> or
>
>                             <code>value3</code>.
>
>                         </para>
>
>                     </wadl:doc>
>
>                 </param>
>
>                 <param xmlns="http://wadl.dev.java.net/2009/02"
>
>                     name="secondParameter" style="plain" type="xsd:string"
> >
>
>                     <wadl:doc xmlns="http://docbook.org/ns/docbook"
>
>                         xmlns:wadl="http://wadl.dev.java.net/2009/02"
> xml:lang="EN">
>
>                         <para>This parameter specifies ... .
>
>                             Valid values are:  <code>value1</code>,
> <code>value2</code> or
>
>                             <code>value3</code>.</para>
>
>                     </wadl:doc>
>
>                 </param>
>
>             </representation>
>
>             <representation mediaType="application/json">
>
>                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
> xml:lang="EN">
>
>                     <xsdxt:code
> href="api_samples/host_modify-request.json"/>
>
>                 </wadl:doc>
>
>             </representation>
>
>         </request>
>
>         <response status="200">
>
>             <representation mediaType="application/xml">
>
>                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
> xml:lang="EN">
>
>                 </wadl:doc>
>                 &hostListShowParameters;
>
>             </representation>
>
>             <representation mediaType="application/json">
>
>                 <wadl:doc xmlns="http://docbook.org/ns/docbook"
> xml:lang="EN">
>
>                     <xsdxt:code
> href="api_samples/host_modify-response.json"/>
>
>                 </wadl:doc>
>
>             </representation>
>
>         </response>
>
>         &postPutFaults;
>
>     </method>
>
>
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141203/6ddaa405/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: image003.png
Type: image/png
Size: 56377 bytes
Desc: not available
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20141203/6ddaa405/attachment-0001.png>