By reza_rahman on Mar 01, 2016
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 manually writing documentation for REST services that are 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. 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.