Self-Documented Services Using Jax-Rs Analyzer
JAX-RS Analyzer reads annotations and metadata and generates documentation.
Join the DZone community and get the full member experience.Join For Free
One of the things I miss the most about SOAP is the fact that much like Java, it is strongly typed. That means one can take a look at a WSDL document to understand what a service does. Similarly, tools can easily read and use a SOAP service including generating clients, GUI visualizations, and accurate documentation.
WADL was conceived of in the REST world to overcome some of these shortcomings. Unfortunately, WADL is sparsely supported and even more sparsely used. This presents a pretty big problem if you are writing REST services that are consumed by folks outside of your own team, and even worse, people that you may not even know. The answer so far has been to manually write documentation for REST services. This is laborious, error-prone and often out of date. (Incidentally, you should be aware that Jersey, the JAX-RS reference implementation, does support WADL).
For JAX-RS developers, though, there is JAX-RS Analyzer to the rescue. JAX-RS Analyzer is a simple but extremely useful open source JAX-RS plugin written by Sebastian Daschner. It reads JAX-RS annotations/metadata to automatically generate documentation in plain text, AsciiDoc or Swagger. The Swagger option is especially compelling, as Swagger is the closest thing at the moment to closing the WSDL/UDDI gap for REST.
If you are still unfamiliar with JAX-RS Analyzer, you should definitely take a look at Sam Sepassi's excellent recent write-up on it. It will save you from hours of tediously documenting your REST APIs.
Published at DZone with permission of Reza Rahman, DZone MVB. See the original article here.
Opinions expressed by DZone contributors are their own.