openstack team mailing list archive

[Frans Thamura <frans@xxxxxxxxxxxx>]

we are working to use swagger, but i think the s/w is not working

can help?

F


On Wed, Oct 26, 2011 at 3:24 AM, Anne Gentle <anne@xxxxxxxxxxxxx> wrote:
> 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
>
>