Add test to reproduce issue #154

[ozscheyge]

Issue: #154
Suggested fix by @romeara (without test): #156

I added a test for reproduction first and will apply changes from #156

Test failure:

Links with the following relations were not found in the response: [self]
org.springframework.restdocs.snippet.SnippetException: Links with the following relations were not found in the response: [self]
	at org.springframework.restdocs.hypermedia.LinksSnippet.validate(LinksSnippet.java:166)
	at org.springframework.restdocs.hypermedia.LinksSnippet.createModel(LinksSnippet.java:123)
	at com.epages.restdocs.apispec.DescriptorValidator$LinksSnippetWrapper.validate(DescriptorValidator.kt:190)
	at com.epages.restdocs.apispec.DescriptorValidator.validateIfDescriptorsPresent(DescriptorValidator.kt:101)
	at com.epages.restdocs.apispec.DescriptorValidator.validatePresentParameters(DescriptorValidator.kt:29)
	at com.epages.restdocs.apispec.ResourceSnippet.document(ResourceSnippet.kt:30)
...

[ozscheyge]

How the resource.json looks for this new test:

{
  "operationId" : "test",
  "summary" : "some summary",
  "description" : "some description",
  "privateResource" : false,
  "deprecated" : false,
  "request" : {
    "path" : "/some/{id}",
    "method" : "GET",
    "contentType" : null,
    "schema" : null,
    "headers" : [ ],
    "pathParameters" : [ ],
    "requestParameters" : [ ],
    "requestFields" : [ ],
    "example" : null,
    "securityRequirements" : null
  },
  "response" : {
    "status" : 200,
    "contentType" : "application/json",
    "schema" : null,
    "headers" : [ ],
    "responseFields" : [ ],
    "example" : "{\n    \"links\": [\n        {\n            \"rel\": \"self\",\n            \"href\": \"http://localhost:8080/some/123\"\n        }\n    ]\n}"
  },
  "tags" : [ "some" ]
}

This isn't quite right yet, since the documented link doesn't show up anywhere.

How (HAL) links are currently rendered in resource.json:

{
  ...
  "response" : {
    ...
    "responseFields" : [ {
      "attributes" : { },
      "description" : "The link to the product default image.",
      "ignored" : false,
      "path" : "productLineItems[].product._links.default-image-data",
      "type" : "OBJECT",
      "optional" : false
    }, {
      "attributes" : { },
      "description" : "The link to the variation product if the product line item is a variation.",
      "ignored" : false,
      "path" : "productLineItems[].product._links.variation-product",
      "type" : "OBJECT",
      "optional" : true
    }, 
    ...
    ]
  }
}

[ozscheyge]

To summarize, what would work:

• ✔️ Validation using a custom link extractor, test doesn't fail validating the atom links

What doesn't work:

• ➖ Link descriptors for non-HAL links aren't included in the response fields in resource.json (restdocs-api-spec's snippet). This is somewhat rooted in the text-snippet-orientied approach of Restdocs and it translated to restdocs-api-spec's ResourceModel (links and LinkDescriptors aren't modeled separately)

Possible solutions:

• Live with the fact: A developer may provide a custom link extractor for validation purposes, but would still need to document links in another way --> relax the current test asserting responseFields size and be done
• Adapt ResourceModel: model links differently from field descriptors. This may need more adaptions to be non-breaking with current model + HAL links