How to document response fields for an object as Map(HashMap)

穿精又带淫゛_ 提交于 2019-12-25 07:00:00

问题


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.



来源:https://stackoverflow.com/questions/37432282/how-to-document-response-fields-for-an-object-as-maphashmap

易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!