Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Self-Documented Services Using Jax-Rs Analyzer

DZone's Guide to

Self-Documented Services Using Jax-Rs Analyzer

JAX-RS Analyzer reads annotations and metadata and generates documentation.

· Integration Zone
Free Resource

Today’s data climate is fast-paced and it’s not slowing down. Here’s why your current integration solution is not enough. Brought to you in partnership with Liaison Technologies.

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.

Is iPaaS solving the right problems? Not knowing the fundamental difference between iPaaS and iPaaS+ could cost you down the road. Brought to you in partnership with Liaison Technologies.

Topics:
jax rs ,rest

Published at DZone with permission of Reza Rahman, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}