openstack team mailing list archive

[Ziad Sawalha <ziad.sawalha@xxxxxxxxxxxxx>]

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.ueno@xxxxxxxxx> 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 <anne@xxxxxxxxxxxxx>:
>> 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
>> anne@xxxxxxxxxxxxx
>> my blog | my book | LinkedIn | Delicious | Twitter
>> On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <heckj@xxxxxxx> 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@xxxxxxxxxxxxxxxxxxx
>>> Unsubscribe : https://launchpad.net/~openstack
>>> More help   : https://help.launchpad.net/ListHelp
>> 
>> 
>> _______________________________________________
>> Mailing list: https://launchpad.net/~openstack
>> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
>> Unsubscribe : https://launchpad.net/~openstack
>> More help   : https://help.launchpad.net/ListHelp
>> 
>> 
> 
> 
> 
> -- 
> Nachi Ueno
> email:nati.ueno@xxxxxxxxx
> twitter:http://twitter.com/nati
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~openstack
> Post to     : openstack@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~openstack
> More help   : https://help.launchpad.net/ListHelp