Spring REST Docs如何记录Multipart表单列表参数？

问题分析 #

你遇到的错误是因为Spring RestDocs默认会严格匹配请求参数名，文档里写的rows[].id和实际请求中的rows[0].id、rows[1].id不匹配，导致校验失败。

解决方案：忽略列表索引 #

Spring RestDocs提供了ignoringIndexes()方法，专门处理这类列表参数的索引问题，允许你用统一的rows[].id格式匹配所有带索引的列表项参数，不用逐个编写带索引的参数名。

修改测试代码中requestParameters部分：

requestParameters(
        parameterWithName("rows[].id").ignoringIndexes().description("row id")
)

完整修改后的测试代码如下：

mockMvc.perform(
        multipart("/sample")
                .file(new MockMultipartFile("file", "level.zip", "application/zip", "level.zip".getBytes()))
                .param("rows[0].id", "1")
                .param("rows[1].id", "2")
                .contentType(MediaType.MULTIPART_FORM_DATA)
        )
        .andDo(document(
                "Sample",
                requestParts(
                        partWithName("file").description("level zip file")
                ),
                requestParameters(
                        parameterWithName("rows[].id").ignoringIndexes().description("row id")
                )
            )
        );

修改后，RestDocs会自动识别所有rows[N].id格式的参数，同时只生成一条关于rows[].id的文档记录，满足你不想写带索引参数名的需求。

进阶可选方案 #

如果需要更灵活的参数匹配规则，可以自定义ParameterMatcher实现自己的参数名匹配逻辑，但对于大多数场景，ignoringIndexes()已经足够简洁好用。

内容的提问来源于stack exchange，提问作者LuxusIo