使用 Spring REST 文档记录分层 JSON 负载

我开始使用Spring REST 文档 http://projects.spring.io/spring-restdocs/记录一个简单的 REST API。我有一个具有某种层次结构的有效负载，例如这样（有员工的公司）。

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

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

我想将公司对象（员工姓名和数组）和员工对象（员工姓名和年龄）的文档分开。

使用org.springframework.restdocs.payload.PayloadDocumentation.responseFields就像解释的那样here http://docs.spring.io/spring-restdocs/docs/1.0.0.RC1/reference/html5/#documenting-your-api-request-response-payloads迫使我记录所有字段，但万一我只想记录employee字段 - 我怎样才能实现这一目标？

我可以在没有员工详细信息的情况下记录公司，因为如果字段是文档，则后代也被视为已记录。但我无法单独记录员工结构，并且在没有公司根对象的情况下，我没有该结构的专用有效负载。

受这个问题的启发，我实现了一项增强功能，使原始答案（见下文）变得过时。

如果您使用 1.0.0.BUILD-SNAPSHOT（可从https://repo.spring.io/libs-snapshot https://repo.spring.io/libs-snapshot），您现在可以将字段标记为忽略。忽略字段计数已被记录，但实际上并未出现在文档中。

考虑到您想要分离文档，进行两个文档调用是有意义的。在第一个中，您可以记录公司名称和员工名单。在第二个中，您记录员工数组并将公司名称标记为忽略。

你的测试看起来像这样：

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打电话是有道理的。在第一个中，您可以记录公司名称和员工名单。在第二步中，您需要预处理删除公司的请求，然后记录员工数组。

你的测试看起来像这样：

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 call. 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每个片段。

虽然上述方法可行，但比实际需要的要困难。我已经打开了an issue https://github.com/spring-projects/spring-restdocs/issues/143这样就不再需要修改响应内容的预处理。