使用Spring REST Docs记录分层JSON有效负载

Question

我开始使用Spring REST Docs来记录一个简单的REST API.我有一个有一些层次结构的有效负载,例如像这样(有员工的公司).

{
    "companyName": "FooBar",
    "employee": 
    [
        {
            "name": "Lorem",
            "age": "42"
        },

        {
            "name": "Ipsum",
            "age": "24"
        }
    ]
}

我想分离公司对象(员工的姓名和数组)和员工对象(员工姓名和年龄)的文档.

使用这里org.springframework.restdocs.payload.PayloadDocumentation.responseFields解释的类似强制我记录所有字段,但万一我只想记录员工字段 - 我怎样才能实现这一目标？

在没有员工详细信息的情况下记录公司没有问题,因为如果字段是文档,则后代也被视为已记录.但我无法单独记录员工结构,如果没有公司根对象,我没有专门的有效负载.

Answer 1

受这个问题的启发,我实施了一项增强功能,使原来的答案(见下文)过时了.

如果使用1.0.0.BUILD-SNAPSHOT(可从https://repo.spring.io/libs-snapshot获得),则现在可以将字段标记为已忽略.已记录忽略的字段数,但实际上没有出现在文档中.

鉴于您想要分离文档,有两个文档调用是有道理的.首先,您可以记录公司名称和员工阵列.在第二个中,您记录了employees数组并将公司名称标记为已忽略.

您的测试看起来像这样:

mockMvc.perform(get("/company/5").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("company",
                responseFields(
                        fieldWithPath("companyName").description(
                                "The name of the company"),
                        fieldWithPath("employee").description(
                                "An array of the company's employees"))))
        .andDo(document("employee",
                responseFields(
                        fieldWithPath("companyName").ignored(),
                        fieldWithPath("employee[].name").description(
                                "The name of the employee"),
                        fieldWithPath("employee[].age").description(
                                "The age of the employee"))));

你最终会得到两个片段目录,一个是名字company,一个是名字employee.然后,您可以使用response-fields.adoc每个代码段.

原始答案

当您记录请求或响应时,没有明确支持忽略字段,但我认为您可以通过使用预处理器删除您不想记录的字段来实现您想要的功能.

鉴于您想要分离文档,有两个document调用是有道理的.首先,您可以记录公司名称和员工阵列.在第二步中,您需要预处理请求以删除公司,然后记录employees数组.

您的测试看起来像这样:

mockMvc.perform(get("/company/5").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("company",
                responseFields(
                        fieldWithPath("companyName").description(
                                "The name of the company"),
                        fieldWithPath("employee").description(
                                "An array of the company's employees"))))
        .andDo(document("employee",
                preprocessResponse(removeCompany()),
                responseFields(
                        fieldWithPath("employee[].name").description(
                                "The name of the employee"),
                        fieldWithPath("employee[].age").description(
                                "The age of the employee"))));

注意preprocessResponse在第二次document调用中使用.removeCompany返回一个预处理器,它使用自定义ContentModifier从响应中删除公司名称:

private OperationPreprocessor removeCompany() {
    return new ContentModifyingOperationPreprocessor(new ContentModifier() {

        @Override
        public byte[] modifyContent(byte[] originalContent, MediaType contentType) {
            ObjectMapper objectMapper = new ObjectMapper();
            try {
                Map<?, ?> map = objectMapper.readValue(originalContent, Map.class);
                map.remove("companyName");
                return objectMapper.writeValueAsBytes(map);
            }
            catch (IOException ex) {
                return originalContent;
            }
        }

    });
}

你最终会得到两个片段目录,一个是名字company,一个是名字employee.然后,您可以使用response-fields.adoc每个代码段.

虽然上述方法有效,但它比它需要的更难.我已经打开了一个问题,因此不再需要修改响应内容的预处理.