how to document trees in Spring REST Docs

Question

I have a tree that returns the following structure:

[{
 "data":
  {
      "id": 15,
      "permissionId": "perm1",
      "name": "Events"
  },
  "children": [
  {
      "data":
      {
          "id": 16,
          "permissionId": "perm2",
          "name": "Report",
          "parentRightDictionaryItemId": 15
      },
      "children": [
      {
          "data":
          {
              "id": 17,
              "permissionId": "perm3",
              "name": "Construct",
              "parentRightDictionaryItemId": 16
          }
      }],

  }]

}]

And I don't understand how to document the fields of this tree, since it can be very deep. What i'm trying to do, this function returns the structure of the documented fields:

protected List<FieldDescriptor> getResponseFieldDescriptor(String prefix) {
    List<FieldDescriptor> fields = new ArrayList<>();

    fields.add(fieldWithPath(prefix + "data").description("data").type(OBJECT));
    fields.add(fieldWithPath(prefix + "data.id").description("id").type(NUMBER));
    fields.add(fieldWithPath(prefix + "data.permissionId").description("permissionId").type(STRING));
    fields.add(fieldWithPath(prefix + "data.name").description("name").type(STRING));
    fields.add(fieldWithPath(prefix + "children").description("children").type(ARRAY).optional());  // I want this to be enough, but that's not enough

    return fields;
}

My function works correctly if the empty number of children. But in the presence of children, an error is returned that I have not documented the entire tree structure. This is a lot. How to do?

Answer 1

I see at least two ways if you only want to document parts of the response and do not want the test to fail on the undocumented parts. A part of a response can be documented with subsectionWithPath :

If you don't want to provide detailed documentation for all of the fields, an entire subsection of a payload can be documented.

An alternative is to use relaxedResponseFields :

Fields can also be documented in a relaxed mode where any undocumented fields will not cause a test failure. To do so, use the relaxedRequestFields and relaxedResponseFields methods on org.springframework.restdocs.payload.PayloadDocumentation.

See https://docs.spring.io/spring-restdocs/docs/2.0.3.RELEASE/reference/html5/#documenting-your-api-request-response-payloads-fields for more details.