openstack team mailing list archive

[Anne Gentle <anne@xxxxxxxxxxxxx>]

All,
Thanks to the generosity of Oxygen in supporting open source projects, you
can edit XML within the Oxygen Author or Editor by downloading a copy of the
software from http://www.oxygenxml.com/. Send an email to support @
oxygenxml dot com requesting the license extension beyond the 30-day trial.

David, you can add information about the plugin (how to get it, etc.) to
http://wiki.openstack.org/Documentation/HowTo.

If you have questions please let me know.
Thanks,
Anne


On Tue, Oct 25, 2011 at 11:27 PM, David Cramer
<david.cramer@xxxxxxxxxxxxx>wrote:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> The wadl normalizer will be on github by early next week. We also have
> a plugin to oXygen [1] for authoring wadls. The plugin does extra
> validation as you type beyond just validating the wadl against the
> schema.
>
> If you need any of that before next week, send me an email and I'll
> make it available to you.
>
> David
>
> [1] http://www.oxygenxml.com/
>
> On 10/25/2011 06:52 PM, Jorge Williams wrote:
> > The hard thing about processing a WADL is that WADLs uses links and
> > references.
> >
> > For example:  WADL A may refer to a method defined in WADL B,
> > that's useful when you're defining extensions.  Or WADL A may
> > define two resources that share GET, PUT, POST operations:  You see
> > this with metadata in servers and images in the compute API
> > /servers/{id}/metadata and /images/{id}/metadata, work exactly the
> > same way, in WADL you don't need to define those operations twice
> > you just link them in to different URIs.
> >
> > Another issue is that there are different ways of defining
> > resources.  You can take a flat approach, much like Swagger uses:
> >
> > <resource path="/resource"/> <resource path="/resource/level2"/>
> > <resource path="/resoruce/level2/level3"/>
> >
> > Or you can take a hierarchical  approach:
> >
> > <resource path="/resource"> <resource path="level2"> <resource
> > path="level3"/> </resource> </resource>
> >
> > What's worse you can have a mixture of the two:
> >
> > <resource path="/resource"> <resource path="level2"> <resource
> > path="level3/level4/level5"/> </resource> </resource>
> >
> > The hard bit is that you need to resolve  all of those links and
> > normalize the paths if you want to process the WADL.  We've (and by
> > we I mean David Cramer),  created a command line tool that can
> > process the WADL and give you a flat normalized WADL that does just
> > that. There are options for flatting the path or expanding and
> > resolving links etc.  The tool just runs the WADL though a couple
> > of XSLT transformations and you end up with an easy to processes
> > WADL on the other end.  You should run this as a preprocessing
> > step, if you plan on writing a script to extract data.  We do this
> > when we process the documents.
> >
> > I know that the WADL normalizer is opensource but not sure where.
> > David, is it on github?
> >
> > -jOrGe W.
> >
> > On Oct 25, 2011, at 6:05 PM, Nati Ueno wrote:
> >
> >> Hi Joe
> >>
> >> 2011/10/25 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'm voting WADL for sure :)
> >>
> >> 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.
> >>
> >> Sorry, It may takes time to open source it because of some paper
> >> works. But it is just 300 lines script.
> >>
> >> I used lxml.objectify http://lxml.de/objectify.html
> >>
> >> You can read wadl as python object. It is very easy to generate
> >> something from the WADL if you know WADL structures.
> >>
> >> xsd_root = objectify.parse("PATH2WADL").getroot()
> >> xsd_root.resoruce_type  #get resource types xsd_root
> >> .iterchildren()   #get childs xsd_root.get('attribute') #get
> >> attributes
> >>
> >>
> >>> 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
> >>>
> >>>
> >>>
> >>
> >>
> >>
> >> -- Nachi Ueno email:nati.ueno@xxxxxxxxx
> >> twitter:http://twitter.com/nati
> >
>
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.11 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
>
> iQEbBAEBAgAGBQJOp4wfAAoJEMHeSXG7afUhGhoH+IgrYtlFu+7d2ao32CphKgRO
> 4o+k7RxquwmDMlfzYWueCFlIlLNnqMc9Dfa869V4/vanXkNSb1ezDfOGvI2f1Qjj
> FSdCOgIXybkKWAMIKqFiVTVJwnMPexzorHn76smYp1jUuJgUXZb36c6MuaFtMcDb
> h1zxlfHYlTzrBrMYcMEje0ZnbIlZcDD4HJg0khfqAsxuwM6CykkcimT6G8iaPqxR
> nDWsrzzx+kvDQscpHDMxcY7mIbUHqEZ6yyXaGZgq4TNL5wG/S74SIWM9BS00bj6Q
> VhDKM3Th1wcKb6BX+EHC0ivDO+fM1B2pg64jKiTJrhPVp48YyKJaIyyfr4fpuA==
> =SdH2
> -----END PGP SIGNATURE-----
>