Hi Nati, I've actually fixed some of the issues you're describing but haven't had a chance to check these in. Let's talk about the issues you're seeing off line and combine our efforts.
-jOrGe W. On Oct 25, 2011, at 3:52 PM, Nati Ueno wrote: > Hi Joe, Anne > > I'm working on WADL of Openstack Diablo in order to generate both of > Test List and API docs from WADL. > I wrote simple script which generate a simple api list from WADL. It > is very helpful. > > Nova and Keystone has WADL, and Ravi@HP is working for glance. > Nova's WADL is inconsistent with the code of Nova, I also fixing it. > And also, I wrote admin api WADL and extensions WADL for nova. (The > bug,joe you mentioned. > https://bugs.launchpad.net/openstack-manuals/+bug/881621) > > Personally, I hate WADL!! It is terrible authoring WADL. > However I don't know there are no other way to describe API specs clearly. > > "Generating something automatically" is may be kind of a dream (or > nightmare :) ) > However, Clear specs are definitely needed for QA. > >> QA Team, let me know how the Docs Team can work with you here. > Thanks! Anne > > 2011/10/25 Anne Gentle <a...@openstack.org>: >> Hi all - >> >> Would also love Swagger. Nati looked into it and he thought it would require >> a Python client generator, based on reading that "Client generators are >> currently available for Scala, Java, Javascript, Ruby, PHP, and Actionscript >> 3." So in the meantime the QA list and Nati suggested WADL as a starting >> point for auto-generating simple API documentation while also looking >> towards Swagger for a way to document a public cloud like the Free Cloud. At >> the last OpenStack hackathon in the Bay Area (California), Nati worked >> through a simple WADL reader, he may be able to describe it better. >> >> Hope that helps - sorry it's not more detailed than that but wanted to give >> some background, sounds like we all want similar outcomes and the resources >> for tasks to get us to outcomes is all we're lacking. QA Team, let me know >> how the Docs Team can work with you here. >> >> Anne >> Anne Gentle >> a...@openstack.org >> my blog | my book | LinkedIn | Delicious | Twitter >> On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <he...@mac.com> wrote: >>> >>> I expect this is going to open a nasty can of worms... today we don't have >>> a consistent way of describing the APIs for the various services. I saw >>> Nati's bug (https://launchpad.net/bugs/881621), which implies that all the >>> services should have a WADL somewhere describing the API. >>> >>> I'm not a huge fan of WADL, but the only other thing I've found is swagger >>> (http://swagger.wordnik.com/spec). I have been working towards trying to >>> create an comprehensive OpenStack API documentation set that can be >>> published as HTML, not unlike some of these: >>> >>> https://dev.twitter.com/docs/api >>> http://developer.netflix.com/docs/REST_API_Reference >>> http://code.google.com/p/bitly-api/wiki/ApiDocumentation#REST_API >>> http://upcoming.yahoo.com/services/api/ >>> >>> To make this sort of web-page documentation effective, I think it's best >>> to drive it from descriptions on each of the projects (if we can). I've >>> checked with some friends who've done similar, and learned that most of the >>> those API doc sets are maintained by hand - not generated from description >>> files. >>> >>> What do you all think about standardizing on WADL (or swagger) as a >>> description of the API and generating comprehensive web-site-based API >>> documentation from those description files? Does anyone have any other >>> description formats that would work for this as an alternative? >>> >>> (I admit I don't want to get into XML parsing hell, which is what it >>> appears that WADL might lead too) >>> >>> -joe >>> >>> >>> _______________________________________________ >>> Mailing list: https://launchpad.net/~openstack >>> Post to : openstack@lists.launchpad.net >>> Unsubscribe : https://launchpad.net/~openstack >>> More help : https://help.launchpad.net/ListHelp >> >> >> _______________________________________________ >> Mailing list: https://launchpad.net/~openstack >> Post to : openstack@lists.launchpad.net >> Unsubscribe : https://launchpad.net/~openstack >> More help : https://help.launchpad.net/ListHelp >> >> > > > > -- > Nachi Ueno > email:nati.u...@gmail.com > twitter:http://twitter.com/nati > > _______________________________________________ > Mailing list: https://launchpad.net/~openstack > Post to : openstack@lists.launchpad.net > Unsubscribe : https://launchpad.net/~openstack > More help : https://help.launchpad.net/ListHelp _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
