All, <br>Thanks to the generosity of Oxygen in supporting open source projects, 
you can edit XML within the Oxygen Author or Editor by 
downloading a copy of the software from <a class="http" href="http://www.oxygenxml.com/">http://www.oxygenxml.com/</a>. Send an email to support @ oxygenxml dot com requesting the license extension beyond the 30-day trial.  <br>

<br>David, you can add information about the plugin (how to get it, etc.) to <a href="http://wiki.openstack.org/Documentation/HowTo">http://wiki.openstack.org/Documentation/HowTo</a>. <br><br>
If you have questions please let me know. <br>
Thanks,<br>Anne<br><br><br><div class="gmail_quote">On Tue, Oct 25, 2011 at 11:27 PM, David Cramer <span dir="ltr"><<a href="mailto:david.cramer@rackspace.com">david.cramer@rackspace.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rgb(204, 204, 204); padding-left: 1ex;">

-----BEGIN PGP SIGNED MESSAGE-----<br>
Hash: SHA1<br>
<br>
The wadl normalizer will be on github by early next week. We also have<br>
a plugin to oXygen [1] for authoring wadls. The plugin does extra<br>
validation as you type beyond just validating the wadl against the<br>
schema.<br>
<br>
If you need any of that before next week, send me an email and I'll<br>
make it available to you.<br>
<br>
David<br>
<br>
[1] <a href="http://www.oxygenxml.com/" target="_blank">http://www.oxygenxml.com/</a><br>
<div><div></div><div class="h5"><br>
On 10/25/2011 06:52 PM, Jorge Williams wrote:<br>
> The hard thing about processing a WADL is that WADLs uses links and<br>
> references.<br>
><br>
> For example:  WADL A may refer to a method defined in WADL B,<br>
> that's useful when you're defining extensions.  Or WADL A may<br>
> define two resources that share GET, PUT, POST operations:  You see<br>
> this with metadata in servers and images in the compute API<br>
> /servers/{id}/metadata and /images/{id}/metadata, work exactly the<br>
> same way, in WADL you don't need to define those operations twice<br>
> you just link them in to different URIs.<br>
><br>
> Another issue is that there are different ways of defining<br>
> resources.  You can take a flat approach, much like Swagger uses:<br>
><br>
> <resource path="/resource"/> <resource path="/resource/level2"/><br>
> <resource path="/resoruce/level2/level3"/><br>
><br>
> Or you can take a hierarchical  approach:<br>
><br>
> <resource path="/resource"> <resource path="level2"> <resource<br>
> path="level3"/> </resource> </resource><br>
><br>
> What's worse you can have a mixture of the two:<br>
><br>
> <resource path="/resource"> <resource path="level2"> <resource<br>
> path="level3/level4/level5"/> </resource> </resource><br>
><br>
> The hard bit is that you need to resolve  all of those links and<br>
> normalize the paths if you want to process the WADL.  We've (and by<br>
> we I mean David Cramer),  created a command line tool that can<br>
> process the WADL and give you a flat normalized WADL that does just<br>
> that. There are options for flatting the path or expanding and<br>
> resolving links etc.  The tool just runs the WADL though a couple<br>
> of XSLT transformations and you end up with an easy to processes<br>
> WADL on the other end.  You should run this as a preprocessing<br>
> step, if you plan on writing a script to extract data.  We do this<br>
> when we process the documents.<br>
><br>
> I know that the WADL normalizer is opensource but not sure where.<br>
> David, is it on github?<br>
><br>
> -jOrGe W.<br>
><br>
> On Oct 25, 2011, at 6:05 PM, Nati Ueno wrote:<br>
><br>
>> Hi Joe<br>
>><br>
>> 2011/10/25 Joseph Heck <<a href="mailto:heckj@mac.com">heckj@mac.com</a>>:<br>
>>> It sounds like even though most of us hate WADL, it's what<br>
>>> we're expending effort after to make a consolidated API set. So<br>
>>> unless Nati and Ravi want to switch to using Swagger (or<br>
>>> something else), WADL is the direction we're heading.<br>
>><br>
>> I'm voting WADL for sure :)<br>
>><br>
>> I totally agree with Daryl that reading it is a PITA, and am<br>
>>> finding (from my part) that the only definitive way to know<br>
>>> about writing the docs and documenting the authoritative API is<br>
>>> to read the underlying code. (which is what I suspect Nati<br>
>>> likely did with the pull request that adds in WADL for the<br>
>>> Nova/OpenCompute extension API) Nati - do you have your WADL<br>
>>> parsing/reading code stashed in a public git repo somewhere<br>
>>> that I could work with and help expand upon? I'd like to see<br>
>>> what I can do to modify it to generate some of the interactive<br>
>>> docs.<br>
>><br>
>> Sorry, It may takes time to open source it because of some paper<br>
>> works. But it is just 300 lines script.<br>
>><br>
>> I used lxml.objectify <a href="http://lxml.de/objectify.html" target="_blank">http://lxml.de/objectify.html</a><br>
>><br>
>> You can read wadl as python object. It is very easy to generate<br>
>> something from the WADL if you know WADL structures.<br>
>><br>
>> xsd_root = objectify.parse("PATH2WADL").getroot()<br>
>> xsd_root.resoruce_type  #get resource types xsd_root<br>
>> .iterchildren()   #get childs xsd_root.get('attribute') #get<br>
>> attributes<br>
>><br>
>><br>
>>> On Oct 25, 2011, at 2:56 PM, Jorge Williams wrote:<br>
>>><br>
>>> We've done quite a bit of work to get high quality<br>
>>> documentation from a WADL,  in fact we are using some of this<br>
>>> today.  We've taken most of the hard work re: parsing the WADL,<br>
>>> at least for the purpose of generating docs from it and of<br>
>>> writing code that can read it (though that later part can use a<br>
>>> bit more work). We are also working to add WADL support in<br>
>>> Repose, which we presented at the summit, you can find the<br>
>>> presentation here:<br>
>>> <a href="https://github.com/rackspace/repose/tree/master/documentation/presentations" target="_blank">https://github.com/rackspace/repose/tree/master/documentation/presentations</a>.<br>
>>><br>
>>><br>
The plan there is to have an HTTP proxy that can do validation of a service<br>
>>> on the fly.  When it's done, you could, for example, turn this<br>
>>> on when you run functional tests and get a gauge as to what<br>
>>> your API coverage is and track both client and service API<br>
>>> errors. Other API tools like Apigee and Mashery already have<br>
>>> support for WADL.  In fact apigee maintains an extensive wadl<br>
>>> library for common APIs:<br>
>>> <a href="https://github.com/apigee/wadl-library" target="_blank">https://github.com/apigee/wadl-library</a>.  There is some WADL<br>
>>> support in python as well, though I haven't tested it first<br>
>>> hand. So obviously, I'd vote for WADL. I haven't looked at<br>
>>> Swagger too deeply, at first glance it *seems* to be missing<br>
>>> some stuff -- but I'll have to study it in detail to be sure.<br>
>>> (How do you define acceptable media types, matrix parameters,<br>
>>> that a particular HTTP header is required?) I don't like the<br>
>>> fact that it tries to describe the format of the message as<br>
>>> well as the HTTP operations.  I'd rather take the approach that<br>
>>> WADL takes which is to rely on existing schema languages like<br>
>>> XML Schema and JSON Schema. What I do like about Swagger is<br>
>>> that you seem to be able to generate some really cool<br>
>>> interactive documentation from it.  I really like their API<br>
>>> explorer feature for example:   You can see it here:<br>
>>> <a href="http://developer.wordnik.com/docs#%21/account/get_word_lists_for_current_user" target="_blank">http://developer.wordnik.com/docs#!/account/get_word_lists_for_current_user</a>.<br>
>>><br>
>>><br>
That's pretty cool.  The thing is though, I could easily generate Swagger<br>
>>> from my WADL :-)  So choosing WADL doesn't necessarily mean<br>
>>> that we can't get access to those tools. Just my 2 cents,<br>
>>> -jOrGe W. On Oct 25, 2011, at 3:24 PM, Anne Gentle wrote:<br>
>>><br>
>>> Hi all -<br>
>>><br>
>>> Would also love Swagger. Nati looked into it and he thought it<br>
>>> would require a Python client generator, based on reading that<br>
>>> "Client generators are currently available for Scala, Java,<br>
>>> Javascript, Ruby, PHP, and Actionscript 3." So in the meantime<br>
>>> the QA list and Nati suggested WADL as a starting point for<br>
>>> auto-generating simple API documentation while also looking<br>
>>> towards Swagger for a way to document a public cloud like the<br>
>>> Free Cloud. At the last OpenStack hackathon in the Bay Area<br>
>>> (California), Nati worked through a simple WADL reader, he may<br>
>>> be able to describe it better.<br>
>>><br>
>>> Hope that helps - sorry it's not more detailed than that but<br>
>>> wanted to give some background, sounds like we all want similar<br>
>>> outcomes and the resources for tasks to get us to outcomes is<br>
>>> all we're lacking. QA Team, let me know how the Docs Team can<br>
>>> work with you here.<br>
>>><br>
>>> Anne Anne Gentle <a href="mailto:anne@openstack.org">anne@openstack.org</a> my blog | my book |<br>
>>> LinkedIn | Delicious | Twitter On Tue, Oct 25, 2011 at 2:41 PM,<br>
>>> Joseph Heck <<a href="mailto:heckj@mac.com">heckj@mac.com</a>> wrote:<br>
>>>><br>
>>>> I expect this is going to open a nasty can of worms... today<br>
>>>> we don't have a consistent way of describing the APIs for the<br>
>>>> various services. I saw Nati's bug<br>
>>>> (<a href="https://launchpad.net/bugs/881621" target="_blank">https://launchpad.net/bugs/881621</a>), which implies that all<br>
>>>> the services should have a WADL somewhere describing the<br>
>>>> API.<br>
>>>><br>
>>>> I'm not a huge fan of WADL, but the only other thing I've<br>
>>>> found is swagger (<a href="http://swagger.wordnik.com/spec" target="_blank">http://swagger.wordnik.com/spec</a>).  I have<br>
>>>> been working towards trying to create an comprehensive<br>
>>>> OpenStack API documentation set that can be published as<br>
>>>> HTML, not unlike some of these:<br>
>>>><br>
>>>> <a href="https://dev.twitter.com/docs/api" target="_blank">https://dev.twitter.com/docs/api</a><br>
>>>> <a href="http://developer.netflix.com/docs/REST_API_Reference" target="_blank">http://developer.netflix.com/docs/REST_API_Reference</a><br>
>>>> <a href="http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API" target="_blank">http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API</a><br>
>>>><br>
>>>><br>
<a href="http://upcoming.yahoo.com/services/api/" target="_blank">http://upcoming.yahoo.com/services/api/</a><br>
>>>><br>
>>>> To make this sort of web-page documentation effective, I<br>
>>>> think it's best to drive it from descriptions on each of the<br>
>>>> projects (if we can). I've checked with some friends who've<br>
>>>> done similar, and learned that most of the those API doc sets<br>
>>>> are maintained by hand - not generated from description<br>
>>>> files.<br>
>>>><br>
>>>> What do you all think about standardizing on WADL (or<br>
>>>> swagger) as a description of the API and generating<br>
>>>> comprehensive web-site-based API documentation from those<br>
>>>> description files? Does anyone have any other description<br>
>>>> formats that would work for this as an alternative?<br>
>>>><br>
>>>> (I admit I don't want to get into XML parsing hell, which is<br>
>>>> what it appears that WADL might lead too)<br>
>>>><br>
>>>> -joe<br>
>>>><br>
>>>><br>
>>>> _______________________________________________ Mailing list:<br>
>>>> <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a> Post to     :<br>
>>>> <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a> Unsubscribe :<br>
>>>> <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a> More help   :<br>
>>>> <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
>>><br>
>>> _______________________________________________ Mailing list:<br>
>>> <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a> Post to     :<br>
>>> <a href="mailto:openstack@lists.launchpad.net">openstack@lists.launchpad.net</a> Unsubscribe :<br>
>>> <a href="https://launchpad.net/%7Eopenstack" target="_blank">https://launchpad.net/~openstack</a> More help   :<br>
>>> <a href="https://help.launchpad.net/ListHelp" target="_blank">https://help.launchpad.net/ListHelp</a><br>
>>><br>
>>><br>
>>><br>
>><br>
>><br>
>><br>
>> -- Nachi Ueno <a href="mailto:email%3Anati.ueno@gmail.com">email:nati.ueno@gmail.com</a><br>
>> twitter:<a href="http://twitter.com/nati" target="_blank">http://twitter.com/nati</a><br>
><br>
<br>
</div></div>-----BEGIN PGP SIGNATURE-----<br>
Version: GnuPG v1.4.11 (GNU/Linux)<br>
Comment: Using GnuPG with Mozilla - <a href="http://enigmail.mozdev.org/" target="_blank">http://enigmail.mozdev.org/</a><br>
<br>
iQEbBAEBAgAGBQJOp4wfAAoJEMHeSXG7afUhGhoH+IgrYtlFu+7d2ao32CphKgRO<br>
4o+k7RxquwmDMlfzYWueCFlIlLNnqMc9Dfa869V4/vanXkNSb1ezDfOGvI2f1Qjj<br>
FSdCOgIXybkKWAMIKqFiVTVJwnMPexzorHn76smYp1jUuJgUXZb36c6MuaFtMcDb<br>
h1zxlfHYlTzrBrMYcMEje0ZnbIlZcDD4HJg0khfqAsxuwM6CykkcimT6G8iaPqxR<br>
nDWsrzzx+kvDQscpHDMxcY7mIbUHqEZ6yyXaGZgq4TNL5wG/S74SIWM9BS00bj6Q<br>
VhDKM3Th1wcKb6BX+EHC0ivDO+fM1B2pg64jKiTJrhPVp48YyKJaIyyfr4fpuA==<br>
=SdH2<br>
-----END PGP SIGNATURE-----<br>
</blockquote></div><br>