Как мне убедиться, что моя документация обновлена ​​с помощью Spring Rest Docs?

Question

Мне очень нравится концепция использования неудачных тестов для обеспечения актуальности документации. Но я не знаю, как заставить это работать для вложенного JSON. То, как Spring REST Docs обрабатывает иерархическую полезную нагрузку, кажется, побеждает цель:

При документировании полей тест не пройден, если в полезной нагрузке будет найдено недокументированное поле. Аналогичным образом, проверка также не будет выполнена, если задокументированное поле не найдено в полезной нагрузке и поле не будет помечено как необязательное. Для полезных нагрузок с иерархической структурой документирования поля достаточно, чтобы все его потомки также рассматривались как задокументированные.

Как бы вы написали свои тесты для вложенного json, чтобы изменения в полезной нагрузке привели к провалу теста?

Пример:

{
car: {
    motor : {
        brand: "Porsche",
        power: "165 kW"
    },

    suspension: {
        type: "automatic"
    }
}

Тестовое задание:

.andDo(document("mytest", responseFields(
                    fieldWithPath("car").description("the car").type(JsonFieldType.OBJECT),
                    fieldWithPath("car.motor").description("the motor").type(JsonFieldType.OBJECT),
                    fieldWithPath("car.motor.brand").description("the motor brand").type(JsonFieldType.STRING),
                    fieldWithPath("car.suspension").description("the suspension"))))

Тест с этими определениями полей ответа будет пройден, даже если car.motor.power и подвеска.type не определены. Есть ли способ заставить его работать? Несколько тестов?

Answer 1

Цель состояла в том, чтобы позволить людям документировать все поля, если они хотят, не заставляя их делать это. Однако, как вы заметили, это может привести к пропуску нового поля в API. Оглядываясь назад, это, вероятно, было ошибкой.

Один из способов избежать пропуска нового поля - документировать только "листовые" поля. В вашем примере это будет:

• car.motor.brand
• car.motor.power
• suspension.type

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

Я понимаю, что ни один из них не является идеальным, поэтому я открыл https://github.com/spring-projects/spring-restdocs/issues/274.