openstack team mailing list archive

[Jorge Williams <jorge.williams@xxxxxxxxxxxxx>]

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 <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