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/