Полезная нагрузка ответа Spring Restdocs содержит необязательный пустой список объектов

Моя полезная нагрузка ответа JSON выглядит следующим образом:

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

Когда я написал Restdocs, как показано ниже, я получил сообщение об ошибке, что items[].k2 = [] не задокументировано.

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

Я пытался написать fieldWithPath("items[].k2[].name").description("...").optional(), но ничего не получилось.


java spring spring-restdocs
person Chris Peng    schedule 20.06.2019    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Это ошибка в Spring REST Docs. Спасибо, что обратили на это мое внимание. Документирования items[].k2[].name должно быть достаточно для того, чтобы items[].k2 считалось задокументированным, поскольку в нем нет недокументированного содержимого. Я открыл эту проблему, чтобы можно было исправить поведение REST Docs.

Пометка поля как необязательного сообщает REST Docs, что тест все равно должен пройти, если поле отсутствует. Это не влияет на необходимость документирования поля. Вот почему пометка поля как optional не решила проблему.

Вы можете обойти проблему, явно задокументировав items[].k2:

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

В качестве альтернативы, если вам не нужна запись в вашей документации для этого поля, вы можете указать REST Docs игнорировать его:

fieldWithPath("items[].k2").ignored()
person Andy Wilkinson    schedule 20.06.2019