如何确保我的文档与Spring Rest Docs是最新的? [英] How do I make sure my documentation is up to date with Spring Rest Docs?

问题描述

我真的很喜欢使用失败的测试来确保文档是最新的概念.但是我不知道如何使它适用于嵌套的json. Spring REST Docs处理分层有效负载的方式似乎无法达到目的:

I really like the concept of using failed tests to ensure the documentation is up to date. But I don't know how to make it work for nested json. The way Spring REST Docs handles hierarchical payload seems to defeat the purpose:

记录字段时，如果在有效负载中找到未记录的字段，则测试将失败.同样，如果在有效负载中未找到记录的字段并且该字段未标记为可选字段，则测试也将失败. 对于具有分层结构的有效负载，记录一个字段就足以将其所有后代也视为已记录.

您将如何为嵌套json编写测试，以便对有效负载进行更改会导致测试失败?

How would you write your tests for nested json so changes to the payload result in a failed test?

示例:

{
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和suspend.type，使用这些响应字段定义的测试也将通过.有办法使它起作用吗?多次测试?

A test with these response field definitions would pass even though car.motor.power and suspension.type are not defined. Is there a way to make it work? Multiple tests?

推荐答案

目的是允许人们在需要时记录所有字段，而不必强迫他们这样做.但是，正如您所观察到的，它可能会导致API中的新字段丢失.事后看来，这可能是一个错误.

The intent was to allow people to document all of the fields if they wanted, without forcing them to do so. However, as you have observed, it can lead to a new field in the API being missed. With hindsight, this was probably a mistake.

避免丢失新字段的一种方法是仅记录叶子"字段.在您的示例中，将是:

One way to avoid missing a new field is to only document "leaf" fields. In your example that would be:

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

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

如果您还想保留更详细的文档，则可以在单独的测试中执行此操作.另一种选择是使用类似JsonPath的方法来声明有效负载的结构.

You could do this in a separate test if you also wanted to keep the more detailed documentation. Another alternative would be to use something like JsonPath to assert the structure of the payload.

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

I realise that none of these is ideal so I've opened https://github.com/spring-projects/spring-restdocs/issues/274.

这篇关于如何确保我的文档与Spring Rest Docs是最新的?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！