Improve beneathPath to work with multiple nested arrays

[Jeff-Walker]

In beneathPath(), paths with an array work now, thanks to #473 and 9e1ba8a. But I'm still having a problem with arrays when there are two levels of arrays in the payload. Consider the payload:

{
  "roles": [
    {
      "key": "1",
      "name": "one",
      "more": [
        {
          "id": 1
        }
      ]
    },
    {
      "key": "1",
      "name": "one",
      "more": []
    }
  ]
}

And I document it like so:

document(snippetName,
        responseFields(
            // beneathPath understands that roles is an array and does the right thing
            beneathPath("roles").withSubsectionId("roles"), 
            fieldWithPath("key").description("key"),
            fieldWithPath("name").description("name"),
            subsectionWithPath("more").description("array")));

This will give me the fields of roles with a description of the more property. To then document the object within the more array, I do a separate snippet:

document(snippetName,
        responseFields(
            // now beneathPath doesn't deal with 'roles' here like it does above
            beneathPath("roles[].more").withSubsectionId("more"), 
            fieldWithPath("[].id").description("id")));

The issue here is that at this point, the second array, the problem is the same as #473, you get a snippet with [] in front of the field path, which is functional, but not great from a documentation standpoint, which is the whole point.

To make this work like the single array, I'd expect maybe beneathPath("roles.more") to work with fieldWithPath("id"), giving me a table with Paths like id in this case.

[nladygin]

Hi got the same problem with a similar response structure root |

• attr:[] |
  • attr:[] |
    • attr

Works with beneathPath("attr[].attr") and "[].attr" only, but looks a little bit ugly in the documentation.