spring-restdocs: responseFields beneathPath does not work with arrays

Using:

org.springframework.restdocs:spring-restdocs-core:2.0.0.RELEASE
org.springframework.restdocs:spring-restdocs-mockmvc:2.0.0.RELEASE

Error:

org.springframework.restdocs.snippet.SnippetException: The following parts of the payload were not documented:
[ {
  "details" : "test details",
  "name" : "testName"
} ]
Fields with the following paths were not found in the payload: [details, name]

Test Code that causes error:

List<FieldDescriptor> responseFieldDescriptors = new ArrayList<>();
responseFieldDescriptors.add(fieldWithPath("details").type(JsonFieldType.STRING).description("Details to display to the customer."));
responseFieldDescriptors.add(fieldWithPath("name").type(JsonFieldType.STRING).description("Customer's name."));


resultActions.andDo(
        MockMvcRestDocumentation.document("content-example",
                preprocessRequest(prettyPrint()),
                preprocessResponse(prettyPrint()),
                responseFields(beneathPath("information.customers[]").withSubsectionId("customer"), responseFieldDescriptors)
        )
);

Test Code that runs but displays unwanted “[].” in generated table

List<FieldDescriptor> responseFieldDescriptors = new ArrayList<>();
responseFieldDescriptors.add(fieldWithPath("[].details").type(JsonFieldType.STRING).description("Details to display to the customer."));
responseFieldDescriptors.add(fieldWithPath("[].name").type(JsonFieldType.STRING).description("Customer's name."));


resultActions.andDo(
        MockMvcRestDocumentation.document("content-example",
                preprocessRequest(prettyPrint()),
                preprocessResponse(prettyPrint()),
                responseFields(beneathPath("information.customers").withSubsectionId("customer"), responseFieldDescriptors)
        )
);

Sample Response:

{
    "information": {
        "customers": [
            "details": "test details",
            "name": "testName"
        ]
    }
}

About this issue

  • Original URL
  • State: closed
  • Created 6 years ago
  • Comments: 22 (10 by maintainers)

Commits related to this issue

Most upvoted comments

Ah, I understand now. Yes, in all likelihood the fix will be made in both 1.2.x and 2.0.x although I’ve yet to figure out what the fix should be…

I’m assuming the open issue means that it still isn’t fixed

Correct.

Is there a workaround so I can make this documentation happen?

I’m not aware of one.

Thanks for the detailed reported.

The sample response that you have shown contains two fields:

  • information.customers.[].details
  • information.customers.[].name

Combining the beneath path and the field path, you are using the following to document the fields:

  • information.customers.details
  • information.customers.name

Neither field exists so REST Docs is correctly failing as two fields that exist have not been documented and an attempt has been made to document two fields that do not exist.

I guess what you’d like to be able to do is to use information.customers.[] as the beneath path? It may not work right now as I think it may be interpreted as identifying a non-unique part of the payload. Have you tried it?