Java 如何使用SpringREST文档将顶级数组记录为响应负载

我正在使用SpringREST文档来记录RESTAPI。我试图记录以下API操作：

GET /subsystems
GET /subsystems/some_name

例如，调用

GET/subsystem/samba

返回以下JSON对象：

{ 
  "id": "samba", 
  "description": "..." 
}

您可以使用以下使用Spring REST文档记录此API操作的代码段：

this.mockMvc.perform(
get（“/subsystem/samba”）.accept（MediaType.APPLICATION_JSON））
.andExpect（status（）.isOk（））.andDo(
文件（“子系统”）。带有ResponseFields(
fieldWithPath（“id”）。描述（“子系统名称”），
字段带路径（“说明”）。说明（“子系统说明”）；

我的问题在于第一个操作：对

GET/subsystem

的调用返回一个JSON数组：

[ 
  { 
    "id" : "samba", 
    "description" : "..." 
  }, 
  { "id" : "ownCloud", 
    "description" : "..." 
  },
  { "id" : "ldap", 
    "description" : "..." 
  } 
]

---

我在SpringREST文档中找不到任何显示如何记录这种结果的示例。我应该怎么做？

这完全可以通过Spring Rest Doc 1.0实现

this.mockMvc.perform(
    get("/subsystems").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("[].id").description("Subsystem name"),
            fieldWithPath("[].description").description("Subsystem description")));

要记录数组本身，请使用

this.mockMvc.perform(
    get("/subsystems").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk()).andDo(
        document("subsystem").withResponseFields(
            fieldWithPath("[]").description("An array of subsystems"),
            fieldWithPath("[].id").ignore(),
            fieldWithPath("[].description").ignore()));

如果您只想记录数组本身，我将忽略其他两个字段。您也可以将这两种解决方案结合起来

享受

---

编辑：我从Andy Wilkinson那里了解到，如果您记录顶级数组，则所有字段都标记为已记录。因此，如果您只想记录数组，可以安全地跳过忽略。

subsectionWithPath

方法的

PayloadDocumentation

也适用于

[]

，无需忽略其余字段：

result.andDo(docHandler.document(
    responseFields(subsectionWithPath("[]").description("A list of objects")
)));

---

我也有同样的问题，你解决了吗？没有，对不起。最后，我决定不使用SpringREST文档。目前它不适合我的需要。我认为springrest文档假定restapi（）中有一个我的API没有实现的最高成熟度级别（这些限制假定您总是必须返回一个JSON对象，而不是一个数组作为顶级元素）。也许Spring REST文档的未来版本将为具有更简单需求的项目放宽这些限制？Spring REST文档不会对REST API的成熟度级别做出任何假设。它提供对3级API的支持（允许您记录API的链接），但可用于记录不太成熟的API。事实上，1.0中唯一的限制是您的API可以通过Spring MVC测试进行测试。谢谢@AndyWilkinson！我会给春季休息医生第二次机会。：-）我已经开始改进文档谢谢@AndyWilkinson！（该问题的链接是）。这在1.1.0上非常有效，但在1.1.1上停止了工作，仍然无法在1.1.2上工作