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.cra...@rackspace.com>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 <he...@mac.com>: > >>> 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 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 > >>> > >>> > >>> > >> > >> > >> > >> -- Nachi Ueno email:nati.u...@gmail.com > >> 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----- >
_______________________________________________ Mailing list: https://launchpad.net/~openstack Post to : openstack@lists.launchpad.net Unsubscribe : https://launchpad.net/~openstack More help : https://help.launchpad.net/ListHelp
