Блог

У меня есть дерево, которое возвращает следующую структуру:

 [{
 "data":
  {
      "id": 15,
      "permissionId": "perm1",
      "name": "Events"
  },
  "children": [
  {
      "data":
      {
          "id": 16,
          "permissionId": "perm2",
          "name": "Report",
          "parentRightDictionaryItemId": 15
      },
      "children": [
      {
          "data":
          {
              "id": 17,
              "permissionId": "perm3",
              "name": "Construct",
              "parentRightDictionaryItemId": 16
          }
      }],

  }]

}]
  

И я не понимаю, как документировать поля этого дерева, поскольку оно может быть очень глубоким.
Что я пытаюсь сделать, эта функция возвращает структуру документированных полей:

 protected List<FieldDescriptor> getResponseFieldDescriptor(String prefix) {
    List<FieldDescriptor> fields = new ArrayList<>();

    fields.add(fieldWithPath(prefix   "data").description("data").type(OBJECT));
    fields.add(fieldWithPath(prefix   "data.id").description("id").type(NUMBER));
    fields.add(fieldWithPath(prefix   "data.permissionId").description("permissionId").type(STRING));
    fields.add(fieldWithPath(prefix   "data.name").description("name").type(STRING));
    fields.add(fieldWithPath(prefix   "children").description("children").type(ARRAY).optional());  // I want this to be enough, but that's not enough

    return fields;
}
  

Моя функция работает правильно, если пустое количество дочерних элементов.
Но при наличии дочерних элементов возвращается ошибка, что я не задокументировал всю древовидную структуру. Это много. Как это сделать?

Я вижу, по крайней мере, два способа, если вы хотите документировать только части ответа и не хотите, чтобы тест завершился неудачей в недокументированных частях. Часть ответа может быть задокументирована с помощью subsectionWithPath :

Если вы не хотите предоставлять подробную документацию для всех полей, можно задокументировать целый подраздел полезной нагрузки.

Альтернативой является использование relaxedResponseFields :

Поля также могут быть задокументированы в упрощенном режиме, где любые недокументированные поля не приведут к сбою теста. Для этого используйте методы relaxedRequestFields и relaxedResponseFields в org.springframework.restdocs.payload.PayloadDocumentation.

Смотрите https://docs.spring.io/spring-restdocs/docs/2.0.3.RELEASE/reference/html5/#documenting-your-api-request-response-payloads-fields для получения более подробной информации.