How to document response fields for an object as M

问题:

I am doing documentation for a REST service returning an object like this:

Map<String, HashMap<Long, String>>

and i find no way to describe response fields for such object.

Let's have a look at my code.

The service:

@RequestMapping(value = "/data", method = RequestMethod.GET)
public Map<String, HashMap<Long, String>> getData()
 {
Map<String, HashMap<Long, String>> list = dao.getData();
return list;
}

My unit-test-based documentation:

  @Test
  public void testData() throws Exception
  {
    TestUtils.beginTestLog(log, "testData");

    RestDocumentationResultHandler document = document(SNIPPET_NAME_PATTERN ,preprocessResponse(prettyPrint()));    
    document.snippets(
 //        ,responseFields(
 //            fieldWithPath("key").description("key description").type("String"),
 //            fieldWithPath("value").description("value as a Hashmap").type("String"),
 //            fieldWithPath("value.key").description("value.key description").type("String"),
 //            fieldWithPath("value.value").description("value.value description").type("String"),
 //        )

      String token = TestUtils.performLogin(mockMvc, "user", "password");

    mockMvc
    .perform(get(APP_BUILD_NAME + "/svc/data").contextPath(APP_BUILD_NAME)
        .header("TOKEN", token)
    )
    .andExpect(status().is(200))
    .andExpect(content().contentType("application/json;charset=UTF-8"))
    .andExpect(jsonPath("$").isMap())
    .andDo(document);

    TestUtils.endTestLog(log, "testData");
 }

As you can see the code for response fields is commented out since I haven't had any solution for it yet. I am working on that but i really appreciate your help. Thank you in advance.

回答1:

Your JSON contains a huge number of different fields. There looks to be over 1000 different entries in the map. Each of those entries is itself a map with a single key-value pair. Those keys all appear to vary as well. Potentially, that gives you over 2000 fields to document:

• cancel
• cancel.56284
• year
• year.41685
• segment_de_clientele
• segment_de_clientele.120705
• …

This structure is making it hard to document and is also a strong indicator that it will be hard to consume by clients. Ideally, you would restructure the JSON so that each entry has the same keys and it's only the values the vary from entry to entry. Something like this, for example:

{
  "translations": [ {
    "name": "cancel",
    "id": 56284,
    "text": "Exit"
  }, {
    "name": "year",
    "id": 41685,
    "text": "Year"
  }, {
    "name": "segment_de_clientele",
    "id": 120705,
    "text": "Client segment"
  }]
}

This would mean that you only have a handful of fields to document:

• translations[]
• translations[].name
• translations[].id
• translations[].text

If that's not possible, then I'd stop trying to use the response fields snippet to document the structure of the response. Instead, you should describe its structure manually in your main Asciidoctor source file.

回答2:

There are two options:

1> Changing MAP to LIST of objects so that the response fields can be described easily.

2> Putting description manually to index.adoc file.

In my case, I go for option 2 because I have to stick to MAP.