openstack team mailing list archive

[Nati Ueno <nati.ueno@xxxxxxxxx>]

Hi Folks

> Daryl
I know to read and write WADL is awful.. because I'm working on that.
My main point is for clear specs. Current docs are very helpful, but
it is not includes
clear specs (parameter structures and types).

>Jorge
Sounds Great
My review request is
https://review.openstack.org/#change,1097
https://review.openstack.org/#change,1098

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

Awesome!
We have 7 integration test tools but we didn't know API coverage of
them it. If we can know
 API coverage automatically such as code coverage, it is very helpful.
# I must not miss your presentation of the summit...

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

I'm agree with you. I checked swagger but it lacks some functions.
Nova and Keystone also have WADLs, so it is easiest way.

-Nati

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