DATAREST-684 - Added details on how to return a HAL document in reference documentation.

Original pull request: #199.

src/main/asciidoc/overriding-sdr-response-handlers.adoc

@@ -16,14 +16,20 @@ public class ScannerController {
     }
 
     @RequestMapping(method = GET, value = "/scanners/search/listProducers") // <2>
-    public @ResponseBody List<String> getProducers() {
+    public @ResponseBody ResponseEntity<?> getProducers() {
         List<String> producers = repository.listProducers(); // <3>
 
         //
         // do some intermediate processing, logging, etc. with the producers
         //
 
-        return producers; // or some filtered/altered/mapped version
+        Resources<String> resources = new Resources<String>(producers); // <4>
+
+        resources.add(linkTo(methodOn(ScannerController.class).getProducers()).withSelfRel()); // <5>
+
+        // add other links as needed
+
+        return ResponseEntity.ok(resources); // <6>
     }
 
 }
@@ -34,6 +40,11 @@ This controller will be served from the same API base path defined in `Repositor
 <1> This example uses constructor injection.
 <2> This handler plugs in a custom handler for a Spring Data finder method.
 <3> This handler is using the underlying repository to fetch data, but will tehn do some form of post processing before returning the final data set to the client.
+<4> The results need to be wrapped up in a Spring HATEOAS `Resources` object to return a collection, but only a `Resource` for a single item.
+<5> Add a link back to this exact method as a "self" link.
+<6> Returning the collection using Spring MVC's `ResponseEntity` wrapper ensure the collection is properly wrapped and rendered in the proper accept type.
+
+`Resources` is for a collection while `Resource` is for a single item. These types can be combined. If you know the links for each item in a collection, use `Resources<Resource<String>>` (or whatever the core domain type is). This lets you assembled links for each item as well as for the whole collection.
 
 IMPORTANT: In this example, the combined path will be `RepositoryRestConfiguration.getBasePath()` + `/scanners/search/listProducers`.