如何确保我的文档与 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 和suspension.type，使用这些响应字段定义的测试也会通过。有没有办法让它工作？多个测试？

Answer 1

其目的是允许人们根据需要记录所有字段，而不是强迫他们这样做。但是，正如您所观察到的，它可能会导致 API 中的一个新字段被遗漏。事后看来，这可能是一个错误。

避免遗漏新字段的一种方法是仅记录“叶”字段。在您的示例中，这将是：

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

如果您还想保留更详细的文档，您可以在单独的测试中执行此操作。另一种选择是使用 JsonPath 之类的东西来断言有效负载的结构。

我意识到这些都不理想，所以我打开了https://github.com/spring-projects/spring-restdocs/issues/274。