Improve support for documenting payloads with multiple sets of links

[wilkinsona]

Inspired by this question on Stack Overflow from @matsev.

I had always assumed that links in embedded resources would be documented as part of the embedded resource's documentation, rather than in the embedding resource's documentation. That may not be an assumption that suits everyone. If you don't want to take this approach then the options currently available are:

1. Use a custom link extractor and produce a single snippet but this means that you can't assert that the links were in the right place in the payload
2. Use a custom snippet, probably a LinksSnippet subclass, and produce two separate snippets with different names.

[matsev]

I have given this problem some more thought and there are some things that need special attention. Consider the following payload:

{
    "foo": {
        "links": {
            "alpha": "http://alpha.example.com/one",
            "bravo": "http://bravo.example.com/one"
        }
    },
   "bar": {
        "links": {
            "alpha": "http://alpha.example.com/two",
            "bravo": ["http://bravo.example.com/one", "http://bravo.example.com/two"],
            "charlie": "http://charlie.example.com",
        }
    }
}

• Rel:s have the same semantic meaning if they have the same name
• The links part of the sub-documents have the same structure
• The foo and bar sub-documents differ
• The url of the alpha rel is different in the foo and bar sub-documents.
• The number of urls are different for the different bravo rel:s.

From a client perspective, this should not be a problem. However, from REST Docs' perspective the rel should only be documented once.

One approach could be to separate the description of rel:s from the the definition of links, e.g.

Map<String, String> rels = rels(
    rel("alpha").description("Alpha description");
    rel("beta").description("Beta description");
    rel("charlie").description("Charlie description");
);

links(rels, 
    customLinks("$.foo.links"),
        linkWithRel("alpha"),
        linkWithRel("beta")),
    customLinks("$.bar.links"),
        linkWithRel("alpha"),
        linkWithRel("beta")
        linkWithRel("charlie")),
);