Diagnostics are poor when an attempt is made to extract a non-existent subsection of a payload

[Jeff-Walker]

Starting in 2.0.3.RELEASE, related to #473. When the beneathPath(jsonPath) doesn't match anything, you get a Jackson exception when you used to get an error message. The obvious workaround is to write the json path properly, but I had a hard time figuring out what what happening.

With 2.0.3.RELEASE:

org.springframework.restdocs.payload.PayloadHandlingException: com.fasterxml.jackson.databind.exc.InvalidDefinitionException: No serializer found for class java.lang.Object and no properties discovered to create BeanSerializer (to avoid exception, disable SerializationFeature.FAIL_ON_EMPTY_BEANS)
  at org.springframework.restdocs.payload.FieldPathPayloadSubsectionExtractor.extractSubsection(FieldPathPayloadSubsectionExtractor.java:100)
  at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:162)
  at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:81)
  at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:201)
  at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55)
  at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:200)

With 2.0.2.RELEASE:

 org.springframework.restdocs.snippet.SnippetException: The following parts of the payload were not documented:
 [ {
   "name" : "John Doe",
   "confNum" : "3204445546546547",
   "moveType" : "I",
   "forwardsUsed" : 1,
   "newForwardExpDate" : "20181215",
   "newPrimaryNum" : "2744",
   "availableExtensions" : [ {
     "optionId" : 2,
     "optionCost" : 19.99,
     "optionLFED" : "20190615"
   }
    ...
   } ],
   "originalMED" : "20170615"
 } ]
 Fields with the following paths were not found in the payload: [name, confNum, moveType, originalMED, forwardsUsed, newForwardExpDate, newPrimaryNum, availableExtensions]
 	at org.springframework.restdocs.payload.AbstractFieldsSnippet.validateFieldDocumentation(AbstractFieldsSnippet.java:261)
 	at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:169)
 	at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:83)
 	at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:206)
 	at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55)
 	at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:200)
 ...

[wilkinsona]

Thanks for the report. This is related to #549 (specifically ada273b) rather than #473.

I'm not sure that I'd consider this a regression. The old behaviour wasn't very helpful as, while it tells you that several fields haven't been documented, it doesn't tell that they haven't been documented because you extracted a non-existent part of the payload. In some ways, I think the new failure is better as it at least homes in on the subsection extraction as being the problem.

Rather than restoring the old behaviour, I think it would be better to make the failure that's now thrown more user-friendly. Throwing a specific exception for a non-existent subsection feels like the most helpful course of action.

[Jeff-Walker]

I agree with this, as the exception told me where my json path was wrong, but I had to dig through your code to figure out why (open source ftw!). I agree also that the old diagnostic took me a while to figure out why I was getting them in the first place.