When a payload has fields with mixed presence documenting those fields may still result in a failure due to undocumented fields

[wilkinsona]

Taken from this question on Stack Overflow, consider the following JSON payload:

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

Documenting the following fields should be sufficient for the payload to be considered fully documented:

• count
• items[].k1
• items[].k2[].name

Instead, REST Docs reports that items[].k2 has not been documented.

When items[].k2[].name is documented, it's removed from its containing object. The object then becomes empty and it's removed from its parent array. This parent array, items[].k2 then becomes empty so it is removed from items. This only works for the second items[].k2 entry in the payload. The first items[].k2 entry is unaffected because it's empty to begin with. As a result, there's no removal of the name entry to trigger the cascading removal of empty containers (objects or arrays).