Hi James,
This looks really interesting! thanks for doing this.
I am going to take a close look at this tomorrow. My first thought is
we should move the Jersey WadlResource class to the API and we
document it in relation to views.
Paul.
On Feb 19, 2009, at 4:04 PM, James Strachan wrote:
> 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/
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: users-unsubscribe_at_jersey.dev.java.net
> For additional commands, e-mail: users-help_at_jersey.dev.java.net
>