Optional subsections are not aware that they are optional.

Hello, I want to document the following payload.

{
  "list" : [ {
    "necessary" : "first",
    "optional" : {
      "field" : "b"
    }
  }, {
    "necessary" : "second"
  } ]
}

list[].optional field is literally an optional field. And here is my documentation code.

responseFields(
        subsectionWithPath("list[]").description("list"),
),
responseFields(
        beneathPath("list[]").withSubsectionId("sub1"),
        fieldWithPath("necessary").description("necessary"),
        subsectionWithPath("optional").description("optional").optional(),
),
responseFields(
        beneathPath("list[].optional").withSubsectionId("sub2"),
        fieldWithPath("field").description("field").optional(),
)

And I got an exception.

list[].optional identifies multiple sections of the payload and they do not have a common structure. The following non-optional uncommon paths were found: [list[].optional]

I’m guessing it’s because the list[].optional path doesn’t have a clue that it is optional (because the fact that list[].optional should be optional appears in the list[] path).

So, is there any feature like beneathPath("path").optional()?

I’m using spring-restdocs-mockmvc:2.0.6

[wilkinsona]

You were relying on a bug, unfortunately.

A wildcard selecting multiple keys in a map is very similar to an array in that we’re then dealing with multiple parts of the payload that need to have the same structure for them to be documented accurately. Differing structures were being missed in some cases and throwing unhelpful errors in others. The changes for #715 mean that differing structures should now always be identified and the error message should be more helpful.

Unfortunately, I don’t think the behaviour you were relying on can be reinstated without regressing that fix.

[ddaaac]

Thank you 😃

I will fix my code.