Open Stack

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 at openstack.org<mailto:anne at openstack.org>
my blog<http://justwriteclick.com/> | my book<http://xmlpress.net/publications/conversation-community/> | LinkedIn<http://www.linkedin.com/in/annegentle> | Delicious<http://del.icio.us/annegentle> | Twitter<http://twitter.com/annegentle>
On Tue, Oct 25, 2011 at 2:41 PM, Joseph Heck <heckj at mac.com<mailto:heckj at 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<https://launchpad.net/%7Eopenstack>
Post to     : openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
Unsubscribe : https://launchpad.net/~openstack<https://launchpad.net/%7Eopenstack>
More help   : https://help.launchpad.net/ListHelp

_______________________________________________
Mailing list: https://launchpad.net/~openstack
Post to     : openstack at lists.launchpad.net<mailto:openstack at lists.launchpad.net>
Unsubscribe : https://launchpad.net/~openstack
More help   : https://help.launchpad.net/ListHelp

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack/attachments/20111025/be513b18/attachment.html>