title: How to automate documentation of a REST API (Jersey Implementation)
body: <p>I have written a pretty extensive REST API using Java Jersey (and JAXB). I have also written the documentation using a Wiki, but its been a totally manual process, which is very error-prone, especially when we need to make modifications, people tend to forget to update the wiki.</p>
  
  <p>From looking around, most other REST API's are also manually creating their documentation. But I'm wondering if theres maybe a good solution to this.</p>
  
  <p>The kind of things which need to be documented for each endpoint are:</p>
  
  <ul>
  <li>Service Name  </li>
  <li>Category</li>
  <li>URI </li>
  <li>Parameter</li>
  <li>Parameter Types</li>
  <li>Response Types</li>
  <li>Response Type Schema (XSD) </li>
  <li>Sample requests and responses</li>
  <li>Request type (Get/Put/Post/Delete) </li>
  <li>Description</li>
  <li>Error codes which may be returned</li>
  </ul>
  
  <p>And then of course there are some general things which are global such as</p>
  
  <ul>
  <li>Security</li>
  <li>Overview of REST</li>
  <li>Error handling</li>
  <li>Etc</li>
  </ul>
  
  <p>These general things are fine to describe once and don't need to be automated, but for the web service methods themselves it seems highly desirable to automate it. </p>
  
  <p>I've thought of maybe using annotations, and writing a small program which generates XML, and then an XSLT which should generate the actual documentation in HTML. Does it make more sense to use custom XDoclet?</p>