How to automate documentation of a REST API (Jersey Implementation) [closed]

Swagger is a beautiful option. It's a project on GitHub, has Maven integration and loads of other options to keep it flexible.

Integration guide: https://github.com/swagger-api/swagger-core/wiki

More Information: http://swagger.io/

Unfortunately, Darrel's answer is technically correct, but is hocus-pocus in the real world. It's based on the ideal that only some agree on and even if you were very careful about it, the chances are that for some reason outside your control, you can't conform exactly.

Even if you could, other developers that might have to use your API may not care or know the details of RESTful patterns... Remember that the point of creating the API is to make it easy for others to use it and good documentation is a must.

Achim's point about the WADL is good however. Because it exists, we should be able to create a basic tool for generating documentation of the API.

Some folks have taken this route, and an XSL stylesheet has been developed to do the transform: https://wadl.dev.java.net/