Spring Restdocs response payload contains optional empty list of objects

Question

My JSON response payload looks like this:

{
  "count": 2,
  "items": [
    {
      "k1": "v1",
      "k2": []
    },
    {
      "k1": "v2",
      "k2": [
        {
          "name": "joe"
        },
        {
          "name": "alice"
        }
      ]
    }
  ]
}

When I wrote Restdocs as bellow, I got an error complaining that items[].k2 = [] is not documented.

responseFields(
  fieldWithPath("count").description("..."),
  fieldWithPath("items[].k1").description("..."),
  fieldWithPath("items[].k2[].name").description("...")
)

I tried to write fieldWithPath("items[].k2[].name").description("...").optional(), but it didn't do anything.

Answer 1

This is a bug in Spring REST Docs. Thanks for bringing it to my attention. Documenting items[].k2[].name should be sufficient for items[].k2 to be considered to be documented as it has no undocumented content. I have opened this issue so REST Docs' behaviour can be fixed.

Marking a field as optional tells REST Docs that the test should still pass if the field is not present. It has no effect on whether or not the field needs to be documented. This is why marking the field as optional has not worked around the problem.

You could work around the problem by explicitly documenting items[].k2:

fieldWithPath("items[].k2").description("...")

Alternatively, if you don't want an entry in your documentation for this field, you could tell REST Docs to ignore it:

fieldWithPath("items[].k2").ignored()