title: Document HAL "_links" from Spring Hateoas (with swagger)?
body: <p>I have a REST service I want to document for my client developing team. </p>
  
  <p>So I added some <code>Links</code> from <code>Spring-Hateoas</code> to my resources API, and plugged into it <code>swagger-springmvc</code> <code>@Api...</code> annotations to document everything and make a good API reference for my Angular team to be able to understand my REST service.</p>
  
  <p>The problem is that <code>swagger</code> is unable to discover what links are possible, and just give me a big array of <code>Links</code> without saying their possible values. </p>
  
  <p>Here is a (simple) example. Swagger detects :</p>
  
  <pre><code>Model Schema
  CollectionListResource {
      collections (array[CollectionResource]): All available collections,
      links (array[Link]): Relations for next actions
  }
  CollectionResource {
      collectionId (string): Collection Unique Id,
      name (string): Human readable collection name,
      links (array[Link]): Relations for next actions
  }
  Link {
      rel (string, optional),
      templated (boolean, optional),
      href (string, optional)
  } 
  </code></pre>
  
  <p>And I get in fact in HAL :</p>
  
  <pre><code> {"collections":
      [{"collectionId":"5370a206b399c65f05a7c59e",
        "name":"default",
         "_links":{ [
             "self":{
                "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
              },
  
             "delete":{
                "href":"http://localhost:9080/collections/5370a206b399c65f05a7c59e"
              }
          ]}
         }, ...]}   
  </code></pre>
  
  <p>I've tried to extend <code>Link</code> and <code>ResourceSupport</code> to have annoted version of them but this lead me to nowhere. </p>
  
  <p>Is there a way/tool I could use to generate a good API doc telling that a <code>self</code> relation is to get the content, and a <code>delete</code> relation is to delete the collection ?</p>
  
  <p>I liked swagger for its good UI, but I don't mind changing my documentation tool if its help having the doc <em>really</em> complete. </p>
  
  <p>I could eventually think of changing spring-hateoas for another link generator, but I'm not sure there is a better tool available right now.</p>