<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Mon, Aug 25, 2014 at 1:12 PM, Waines, Greg <span dir="ltr"><<a href="mailto:Greg.Waines@windriver.com" target="_blank">Greg.Waines@windriver.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal">Some basic questions on editing the REST APIs in openstack/api-site:<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">ok so I have cloned the api-site git:<u></u><u></u></p>
<p class="MsoNormal">i.e. git clone <a href="https://github.com/openstack/api-site.git" target="_blank">
https://github.com/openstack/api-site.git</a><u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">I have installed maven and done a build<u></u><u></u></p>
<p class="MsoNormal">i.e. <u></u><u></u></p>
<p class="MsoNormal">sudo apt-get install maven<u></u><u></u></p>
<p class="MsoNormal">cd api-site/<u></u><u></u></p>
<p class="MsoNormal">mvn clean generate-sources<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">… and the PDFs and HTML files all build.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">Now trying to EDIT files …<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">I downloaded a trial copy of Oxygen, and<u></u><u></u></p>
<p class="MsoNormal">installed the ‘wadl-tools’ and ‘racbook’ addons.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> </p></div></div></blockquote><div><br></div><div>Congrats, you've just passed the first hurdles. Nicely done.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple"><div><p class="MsoNormal"><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">QUESTIONS:<u></u><u></u></p>
<p class="MsoNormal">- say I want to update the response of the NOVA list flavor details<u></u><u></u></p>
<p class="MsoNormal">- what are the files to edit ? … and is Oxygen the editor to use even for the wadl files ?<u></u><u></u></p>
<p class="MsoNormal"><u></u> </p></div></div></blockquote><div><br></div><div>Yes.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple"><div><p class="MsoNormal"><u></u></p>
<p class="MsoNormal">- I tried opening with Oxygen<u></u><u></u></p>
<p class="MsoNormal"> ./api-site/api-ref-guides/src/bk-api-ref-compute-v2.xml
<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">- in Author mode,<u></u><u></u></p>
<p class="MsoNormal"> Oxygen shows the included file:<u></u><u></u></p>
<p class="MsoNormal"> ./api-site/api-ref/src/docbkx/ch_compute-v2.xml<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">- I go down to … Section 1.8: Flavors<u></u><u></u></p>
<p class="MsoNormal"> Oxygen shows me a wadl resources tag with 3x wadl resource / wadl method tags.<u></u><u></u></p>
<p class="MsoNormal"> > with the wadl resource tag<br>
with a reference to a <br>
./api-site/api-ref/src/wadls/compute-api/src/v2/wadl/os-compute-2.wadl#Flavors<u></u><u></u></p>
<p class="MsoNormal"> > and the wadl method tag<u></u><u></u></p>
<p class="MsoNormal"> with a reference (href) to #listDetailFlavors<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">??? Oxygen seems to allow you the edit the reference (href) itself.</p></div></div></blockquote><div><br></div><div>No, as far as I can tell Oxygen (even with wadl-tools installed) does not know to open WADLs within itself.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><u></u><u></u></p>
<p class="MsoNormal"> But doesn’t seem to let you open up this referenced .wadl file thru a context menu.<u></u><u></u></p>
<p class="MsoNormal">??? are you supposed to just open the .wadl file with Oxygen manually ???<u></u><u></u></p>
<p class="MsoNormal"><u></u> </p></div></div></blockquote><div><br></div><div>Yes, I have to choose XML every time I open a WADL file with Oxygen on my Mac.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple"><div><p class="MsoNormal"><u></u></p>
<p class="MsoNormal">Assuming yes … <u></u><u></u></p>
<p class="MsoNormal">I can find the resource_type tag for defining the detail flavor list.<u></u><u></u></p>
<p class="MsoNormal">which has a method tag with an href to #listDetailFlavors … in this file.<u></u><u></u></p>
<p class="MsoNormal"> SIDE QUESTION: not sure I understand the difference between resources and resource_types in this file ?</p></div></div></blockquote><div><br></div><div>I just had that discussion the other day internal to Rackspace, other writers ask the same thing. Here's all I could come up with, but maybe someone on this list has more answers. Perhaps it's a useful short-cut at the top of the WADL that provides "anchor links" to the rest of the long file. Jorge, any thoughts here? </div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">I can find the method tag for defining the listDetailFlavor method.<u></u><u></u></p>
<p class="MsoNormal">which has a number of subtags for title, request, parameters, json response, xml response …<u></u><u></u></p>
<p class="MsoNormal">The representation tag for documenting (say) the json format has a xsdxt:code with an href to<br>
./api-site/api-ref/src/wadls/compute-api/src/v2/api_samples/os-flavor-list-resp.json<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">??? again, are you supposed to just open the .json file with Oxygen manually and edit ???<u></u><u></u></p>
<p class="MsoNormal"><u></u> </p></div></div></blockquote><div><br></div><div>Yes, just edit A bit of history, for Compute those samples were maintained for v2 in the nova repo itself and tested with code commits, but now they are only in the api-site repo it looks like. (Yowsa, they were the only project who ever tested their API samples with each commit, guess that's no longer the case.)</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div>
<p class="MsoNormal"><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">apologies for somewhat scattered questions,</p></div></div></blockquote><div><br></div><div>No need, these are good questions. </div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple"><div><p class="MsoNormal"><u></u><u></u></p>
<p class="MsoNormal">I guess the high-level question was that I thought the editing of REST API methods with Oxygen would<br>
be somewhat more WYSIWYG.<u></u><u></u></p>
<p class="MsoNormal">Instead of really editing the detailed XML / WADL / JSON files.<span class=""><font color="#888888"><u></u><u></u></font></span></p><span class=""><font color="#888888">
<p class="MsoNormal"><u></u></p></font></span></div></div></blockquote><div><br></div><div>Yeah it's really hard isn't it? I'd love to get us to Swagger or RAML with their nice side-by-side web editors, but this is the current state. Thanks for asking so nicely and not ranty. :)</div>
<div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple">
<div><span class=""><font color="#888888"><p class="MsoNormal"> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal">Greg.<u></u><u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
<p class="MsoNormal"><u></u> <u></u></p>
</font></span></div>
</div>
<br>_______________________________________________<br>
Openstack-docs mailing list<br>
<a href="mailto:Openstack-docs@lists.openstack.org">Openstack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
<br></blockquote></div><br></div></div>