Spring REST Doc unamed request parameter

Question

I am writing the documentation of my rest service using the Spring REST Docs library .

A problem I have is that I accept a POST request with a JSON structure as an input that does not have any name.

The request looks something like this :

POST /images?limit=3&offset=12 HTTP/1.1
Content-Type: application/json
Host: localhost:8080
Content-Length: 289

{"acquisitionWindow":0,"platformName":"myPlatform","requireImageFile":false,"requireImageFileOrQuicklook":false,"strictPolygon":false,"showInternal":false,"imageNames":["%"],"startTimeOfYear":0,"stopTimeOfYear":0,"resolutionLowerBound":0.0,"resolutionUpperBound":0.0,"reducedResolution":0}

I would like to document the input structure, but have found no way to do it so far.

The documentation describes something like this :

this.mockMvc.perform(get("/users?page=2&per_page=100")) 
    .andExpect(status().isOk())
    .andDo(document("users", requestParameters( 
            parameterWithName("page").description("The page to retrieve"), 
            parameterWithName("per_page").description("Entries per page") 
    )));

But my parameter has no name.

What I have tried to far :

requestParameters(
    // TODO: Insert ImageSearch here
    parameterWithName("{}").description("ImageSearch Structure "))

I have also tried with an empty name ("") , and the array notation ("[]") . No luck so far.

Is it possible to document unamed parameters, or should I wrap it in another structure?

Thanks,

Answer 1

You can use requestFields on org.springframework.restdocs.payload.PayloadDocumentation to document the JSON payload that's sent in the request. For example:

this.mockMvc.perform(get("/users?page=2&per_page=100")) 
    .andExpect(status().isOk())
    .andDo(document("users", requestFields( 
            fieldWithPath("acquisitionWindow").description("…"), 
            fieldWithPath("platformName").description("…"))));

See the Request and response payloads section of the documentation for some further details.