Posted by stoicflame
on March 13, 2009 at 3:12 PM PDT
If you're using JAX-WS or JAX-RS to provide a Web service API, think about generating documentation and client-side classes (Java, C#, ActionScript) at compile-time. It's easier than you might think.
So you've got your JAX-WS or JAX-RS endpoints defined and implemented, and they're compiling, building and running smooth on your server. All is well, right? You've been diligent in documenting and testing your code, and the consumers of your API seem to be happy.
Well, that's just because they don't know what they're missing.
Here's the thing: your Web service API could be so much better. What if you could leverage all that work you've put into your JavaDocs and publish that as documentation for your API? And what if you could provide fully-documented, well-formated, strongly-typed client-side code for your .NET, Java, or ActionScript clients?
With just some enhancements to your build file or your POM, you can produce stuff that looks like this for your Web service API.
Let's say you're using Maven to build your project. Just use the Maven Enunciate Plugin to export your own docs to the target/docs directory:
Or if you're using Ant, you can do the same thing with something like this:
<export artifactId="docs" destination="target/docs"/>
That's it. Try it out. Check out the Enunciate documentation to learn more.