openstack team mailing list archive

[Joseph Heck <heckj@xxxxxxx>]

It sounds like even though most of us hate WADL, it's what we're expending effort after to make a consolidated API set. So unless Nati and Ravi want to switch to using Swagger (or something else), WADL is the direction we're heading. I totally agree with Daryl that reading it is a PITA, and am finding (from my part) that the only definitive way to know about writing the docs and documenting the authoritative API is to read the underlying code. (which is what I suspect Nati likely did with the pull request that adds in WADL for the Nova/OpenCompute extension API)

Nati - do you have your WADL parsing/reading code stashed in a public git repo somewhere that I could work with and help expand upon? I'd like to see what I can do to modify it to generate some of the interactive docs.

On Oct 25, 2011, at 2:56 PM, Jorge Williams wrote:
> We've done quite a bit of work to get high quality documentation from a WADL,  in fact we are using some of this today.  We've taken most of the hard work re: parsing the WADL, at least for the purpose of generating docs from it and of writing code that can read it (though that later part can use a bit more work).
> 
> We are also working to add WADL support in Repose, which we presented at the summit, you can find the presentation here: https://github.com/rackspace/repose/tree/master/documentation/presentations. The plan there is to have an HTTP proxy that can do validation of a service on the fly.  When it's done, you could, for example, turn this on when you run functional tests and get a gauge as to what your API coverage is and track both client and service API errors.
> 
> Other API tools like Apigee and Mashery already have support for WADL.  In fact apigee maintains an extensive wadl library for common APIs: https://github.com/apigee/wadl-library.  There is some WADL support in python as well, though I haven't tested it first hand.
> 
> So obviously, I'd vote for WADL.
> 
> I haven't looked at Swagger too deeply, at first glance it *seems* to be missing some stuff -- but I'll have to study it in detail to be sure. (How do you define acceptable media types, matrix parameters, that a particular HTTP header is required?)
> 
> I don't like the fact that it tries to describe the format of the message as well as the HTTP operations.  I'd rather take the approach that WADL takes which is to rely on existing schema languages like XML Schema and JSON Schema. 
> 
> What I do like about Swagger is that you seem to be able to generate some really cool interactive documentation from it.  I really like their API explorer feature for example:   You can see it here:  http://developer.wordnik.com/docs#!/account/get_word_lists_for_current_user.   That's pretty cool.  The thing is though, I could easily generate Swagger from my WADL :-)  So choosing WADL doesn't necessarily mean that we can't get access to those tools.
> 
> Just my 2 cents,
> 
> -jOrGe W.
> 
> On Oct 25, 2011, at 3:24 PM, Anne Gentle 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
>