Spring Restdocs response payload contains optional empty list of objects

user_3667559 0
Viewed 3737

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.

spring-restdocs spring java
1 Answers

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()
user_13842970
Related