как документировать деревья в Spring REST Docs - PullRequest
Новая
       9

как документировать деревья в Spring REST Docs

1 голос
/ 23 апреля 2019

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

[{
 "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;
}

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

1 Ответ

2 голосов
/ 23 апреля 2019

Я вижу по крайней мере два способа, если вы хотите документировать только части ответа и не хотите, чтобы тест не прошел на недокументированных частях.Часть ответа может быть задокументирована с помощью 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.

...