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 <a...@openstack.org> 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 > 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 > > _______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
