Spring REST Docs 文档化Map<Object, Set<Object>>类型字段遇到问题

你遇到的问题是典型的动态键字段文档化场景——因为virtualFaxPermissions下的键是随机生成的UUID，不是固定字段名，Spring Rest Docs默认无法识别这种动态结构，直接传入Map或者错误使用通配符都没法覆盖所有未文档化的部分。

下面是具体的解决步骤：

1. 用通配符*匹配动态UUID键 #

你需要针对动态键和其对应的权限数组分别配置字段描述，核心是用*作为通配符来匹配所有UUID键：

payloadFields(
    // 先文档化顶层的映射字段
    fieldWithPath("virtualFaxPermissions")
        .description("虚拟传真机权限映射，键为传真机的UUID"),
    // 匹配所有动态UUID对应的权限集合
    fieldWithPath("virtualFaxPermissions.*")
        .description("单个虚拟传真机的权限集合"),
    // 匹配集合中的每个权限元素
    fieldWithPath("virtualFaxPermissions.*[]")
        .description("具体的权限值，例如`SOME_SPECIFIC_PERMISSION`")
)

2. 为什么之前的方法无效？ #

• 直接把virtualFaxPermissionsSetMap传给description()：这只是给顶层字段加了描述，但没有文档化嵌套的动态键和数组元素，Rest Docs依然会认为这些子字段未被覆盖。
• 错误使用通配符：如果只给顶层字段加通配符，没有深入到数组元素层级，同样会遗漏部分字段。

3. 进阶：指定权限的可选值（可选） #

如果需要明确列出权限的可能取值，可以给字段描述符添加属性：

fieldWithPath("virtualFaxPermissions.*[]")
    .description("授予该虚拟传真机的权限")
    .attributes(key("允许的值").value("SOME_SPECIFIC_PERMISSION, FAX_SEND, FAX_RECEIVE"))

4. 验证效果 #

运行测试后，检查生成的API文档片段，确保virtualFaxPermissions下的所有动态结构都被正确文档化，不会再抛出SnippetException。

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