Make it easy to document a subset of a request or response's fields

[dsyer]

I have found that I want to document the existence of the fields (with some brief description) in the table (or something similar), and then make more detailed notes about the content below that, with separate snippets for each subfield that I want to document. This means that I need a new snippet type for an individual response field, something like new ResponseFieldSnippet("foo.bar") to extract the foo.bar field from the response.

The only difficult part for me has been parsing the field specification ("foo.bar" in the example above) and extracting the right parts of the response. Especially difficult when one of the fields traversed is an array because you might want a specific array element and be unwilling to specify it by index (in case the order wasn't deterministic).

A further complication with arrays is that the logical file name for an extracted field snippet is the path used to extract it ("foo.bar" in the example generates "foo.bar.adoc"), but if the path has an array index (e.g. "foo.bar[0]") then you can't include it in Asciidoctor because of the way the include gets parsed. I had to adopt a convention that I stripped out the indexed parts from a path before I generated the file name.

[dsyer]

Here's an example of the sort of output I need: https://github.com/spring-io/initializr/wiki/Metadata-format

[wilkinsona]

Thanks, @dsyer. The documentation for a sub-field in your example seems to be free-form text. I can't see what REST Docs could validate for you. What have I missed?

I can see how this would work for what @AnnaMaus86 described in #277. The goal there was to do what GitHub does in their docs where there's a table that documents the sub-section.

In that case the request payload looks like this:

{
  "tag": "v0.0.1",
  "message": "initial version\n",
  "object": "c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c",
  "type": "commit",
  "tagger": {
    "name": "Scott Chacon",
    "email": "[email protected]",
    "date": "2011-06-17T14:53:35-07:00"
  }
}

Two snippets could be produced something like this:

mockMvc.perform(
        post("/repos/{owner}/{repo}/git/tags").accept(MediaType.APPLICATION_JSON))
        .andExpect(status().isOk())
        .andDo(document("tag-creation",
                responseFields(
                        fieldWithPath("tag").description("…"),
                        fieldWithPath("message").description("…"),
                        fieldWithPath("object").description("…"),
                        fieldWithPath("type").description("…"),
                        fieldWithPath("tagger").description("…")),
                responseFields("tagger",
                        fieldWithPath("name").description("…"),
                        fieldWithPath("email").description("…"),
                        fieldWithPath("date").description("…"))));

The tagger argument to the second responseFields call is what extracts a particular sub-section of the payload to be documented. To cover the more complex case where you want a particular element of a variably ordered array, this could be expanded to support full-blown JSON path or perhaps just a strategy interface that you can implement where you're called with the full payload and you return the relevant bit of it.

[dsyer]

In my case it's not free form text, but rather the field value that I'm interested in. The table form in your example might also be useful, but I'd like to be able to just include the value of the field as an example, rather than create a table of sub-field descriptions.

[wilkinsona]

Thanks, @dsyer. The first step toward what you want would appear to be a snippet for the body of a request or a response. I've opened #318 for that. The ability to produce a snippet for a portion of a request or response body could then be built on top of that (#319). I'll keep this issue for the table-based approach I described above.