The WADL is unfortunately not complete for Nova, Glance, and Quantum - I believe Keystone has been keeping it quite up to date as the changes to the API have been being made. Nachi's made a couple of pull requests today for updates to the WADL related to the OpenStack API, and offered to help create a WADL (which didn't exist previously) for Quantum.
-joe On Oct 25, 2011, at 7:25 PM, Ziad Sawalha wrote: > Hi Nati - I might be opening a can of worms here, but I thought the API spec > and WADL were complete and we were working on implementing it. It sounds to > me like you are doing the reverse and matching the WADL to the current state > of the code. There's value in that, but i know it will cause problems for > anyone trying to rely and code to the spec (which I know we are). > > Z > > > > On Oct 25, 2011, at 4:00 PM, "Nati Ueno" <nati.u...@gmail.com> 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 _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
