Как документировать рекурсивные структуры данных в ответ на Spring REST Docs - PullRequest
Новая
       54

Как документировать рекурсивные структуры данных в ответ на Spring REST Docs

0 голосов
/ 30 января 2020

У меня вопрос по поводу Spring Restdocs. Один из остальных вызовов, которые я хочу задокументировать, возвращает рекурсивную структуру данных с различными типами потомков: leaf и поддерево. Лист и поддеревья имеют разные атрибуты. Например: 

{
    "id": "$",
    "left": {
        "id": "l",
        "left": {
            "id": "l1",
            "type": "leaf",
            "value": "Leaf 1"
        },
        "right": {
            "id": "l2",
            "type": "leaf",
            "value": "Leaf 2"
        },
        "type": "subtree"
    },
    "right": {
        "id": "l3",
        "type": "leaf",
        "value": "Leaf 3"
    },
    "type": "subtree"
}

Я не мог найти, как документировать эти рекурсивные структуры данных с помощью Spring Restdocs. Есть кто-нибудь пример или может помочь мне.

У меня есть репо git с кодом, который показывает мою проблему: https://github.com/dibog/spring-restdocs-recursive-demo

С уважением, Дитер

1 Ответ

0 голосов
/ 30 января 2020

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

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

responseFields(beneathPath("left.left").withSubsectionId("leaf"),
    fieldWithPath("id").description("ID of the node"),
    fieldWithPath("type").description("Type of the node. Always 'leaf' for leaf nodes"),
    fieldWithPath("value").description("Value of the node")),
responseFields(beneathPath("left").withSubsectionId("subtree"),
    fieldWithPath("id").description("ID of the node"),
    fieldWithPath("type").description("Type of the node. Always 'subtree' for nodes with children"),
    subsectionWithPath("left").description("Left-hand child node. Either a subtree or a leaf"),
    subsectionWithPath("right").description("Right-hand child node. Either a subtree or a leaf"))

Использование subsectionWithPath при документировании узла поддерева позволяет вам покрыть все поддерево одним дескриптором. Описание информирует пользователя о том, что значения left и right будут узлом, который является либо листом, либо другим поддеревом.

...