Skip to main content

Add some sugar to your Web service API

Posted by stoicflame on March 13, 2009 at 3:12 PM PDT

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:

<plugin>
  <groupId>org.codehaus.enunciate</groupId>
  <artifactId>maven-enunciate-plugin</artifactId>
  <version>1.10</version>
  <executions>
    <execution>
      <goals>
        <goal>docs</goal>
      </goals>
      <configuration>
        <docsDir>${project.build.directory}/docs<docsDir>
      </configuration>
    </execution>
  </executions>
</plugin>

Or if you're using Ant, you can do the same thing with something like this:

<enunciate basedir="src/main/java">
  <include name="**/*.java"/>
  <classpath refid="enunciate.classpath"/>
  <export artifactId="docs" destination="target/docs"/>
</enunciate>

That's it. Try it out. Check out the Enunciate documentation to learn more.

http://enunciate.codehaus.org/

Related Topics >>

Comments

It'll document your JAX-RS endpoints just like it would document your JAX-WS endpoints. To see you your REST endpoints might be documented, see this example: http://enunciate.codehaus.org/wannabecool/step4/index.html It only has one REST endpoint, though. We should probably beef that up a bit, but you get the point. This quick example is supposed to demonstrate a mixture of SOAP/REST endpoints on the same API.

I fail to see how this is useful for JAX-RS. The example site seems SOAP oriented.

Indeed ;-). We've tried to make a concerted effort to reduce dependency bloat, but there are a lot of external libraries that we reference. If you're just using the docs plugin, though, you won't be adding any dependencies to the project itself--it's all compile-time.

cool plugin, but for sure this guys from enunciate reached the world record in terms of dependencies.. be prepared for a long coffee while the Maven download all the stuff :)