I love the idea of a self-documenting REST service over both HTML and XML. While I really like the automatic WADL generation; I didn't want to have to mess with XSLT to be able to render the API for a RESTful application nicely in HTML. Plus for a hierarchical API - it would be nice to render the API in stages letting folks navigate around the API rather than getting API overload in one huge doc.

So here's a minor patch that lets users use Implicit Views to render a nice HTML representation of the API. https://jersey.dev.java.net/issues/show_bug.cgi?id=223

There's an example of using this in the Camel project... https://svn.apache.org/repos/asf/camel/trunk/components/camel-web/

e.g. here are the 2 implicit views of the root level WadlResource (the application basically) and then each child WadlResoureResource which then lets users walk as deep into the API as they want... https://svn.apache.org/repos/asf/camel/trunk/components/camel-web/src/main/webapp/com/sun/jersey/server/impl/wadl/

The magic to render a resource nicely in JSP is done via this <api:resource> JSP tag https://svn.apache.org/repos/asf/camel/trunk/components/camel-web/src/main/webapp/WEB-INF/tags/api/resource.tag

In terms of the patch, I added one extra configuration property, letting the user override the URI used to expose the WADL XML view. If not specified it maintains the current behaviour and defaults to "application.wadl". However an application may decide to use another URI such as "/api".

For example in Camel I added this to the servlet config https://svn.apache.org/repos/asf/camel/trunk/components/camel-web/src/main/webapp/WEB-INF/web.xml

<init-param> <param-name>com.sun.jersey.config.property.WadlResourceUri</ param-name> <param-value>/api</param-value> </init-param>

Then I've made a few enhancements to the WadlResource so that it can be rendered as Implicit Views. Also you can navigate within the API resource to sub-resources so that you can then have a hierarchical HTML representation of the resources at any URI.

For example in the Camel project there's a root URI '/' then child resources 'endpoints' and 'routes'. If you click on 'endpoints' in the UI you are directed from '/api' to /api/resources/endpoints' where you can then navigate into '{id}' to view the APIs on an endpoint and so on. This lets you walk the API recursively with your browser and hypertext links. e.g. all these links work fine

http://localhost:8080/api/resources http://localhost:8080/api/resources/endpoints http://localhost:8080/api/resources/endpoints/{id}

which also means folks can then link to specific API (resource) bits of documentation. You can still access the WADL via http://localhost:8080/api (with Accept text/xml) or via http://localhost:8080/api.xml

Its a fairly minor patch; I've added a few helper methods to the WadlResource and the new child WadlResourceResource (lousy name :) to make it very easy to render nicely in JSP.

I've just not tested yet if an application which has no "/" resource but instead has 2 peer resources, say "/foo" and "/bar" which have child resources - if the resource navigation works properly; I think it should, but we could do with testing it to be sure.

Am sure I'm not alone in trying to avoid the use of XSLT - so letting folks use Implicit Views to render their APIs would be very cool :)

Thoughts?

-- James

------- http://macstrac.blogspot.com/

Open Source Integration http://fusesource.com/