Document that the query string should be provided in the URL or by using queryParam when using MockMvc

[nick-shevchenko]

Greetings!

Query parameters are ignored when using param builder:

mockMvc.perform(
            delete("/v1/event/configs/delete")
                .param("eventName", "CART2")
                .param("name", "available")
            )
            .andExpect(status().isOk)
            .andDo(document("delete-event-config"))

However, this one works:

mockMvc.perform(
            delete("/v1/event/configs/delete?eventName=CART2&name=available"))
            .andExpect(status().isOk)
            .andDo(document("delete-event-config"))

Using: org.springframework.boot:spring-boot:3.2.3 org.springframework.restdocs:spring-restdocs-mockmvc:3.0.1 org.springframework.restdocs:spring-restdocs-asciidoctor:3.0.1

[wilkinsona]

Thanks for the report.

The problem here is that the param method is ambiguous. It adds the parameter directly to the parameter map that's a server-side construct that can be populated from either the query string of the HTTP request's URI or from the body of the HTTP request if it's an application/x-www-form-urlencoded request. In your example above, you've used the param method and haven't specific a content type so REST Docs has to guess your intent. It's getting that wrong for your usage and incorrectly assuming that you intended the parameters to be included in the request's body.

You can avoid the ambiguity described above, either by including the query parameters directly in the URL as you have done above, or by using the queryParam method instead of the param method.

REST Docs' documentation could certainly be improved in this area. Beyond that, I'm not sure what can be done as changing the current behavior risks breaking someone's existing usage. One option is to make some changes in Framework so that it's harder to get into this situation. I've opened https://github.com/spring-projects/spring-framework/issues/32757 to discuss that with the Framework team.