Wie Antwortfelder für ein Objekt als Karte (HashMap)

Question

ich tue Dokumentation für eine REST-Service Rückkehr ein Objekt so zu dokumentieren.

Werfen wir einen Blick auf meinen Code.

Der 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-basierte Dokumentation:

@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"); 
} 

Wie Sie den Code für die Antwortfelder sehen kann, ist auf Kommentar, da ich keine Lösung für gehabt haben es jetzt. Ich arbeite daran, aber ich schätze Ihre Hilfe sehr. Vielen Dank im Voraus.

Answer 1

Es gibt zwei Möglichkeiten:

1> MAP zur Liste der Objekte ändern, so dass die Antwortfelder leicht beschrieben werden können.

2> Beschreibung manuell in die Datei index.adoc einfügen.

In meinem Fall gehe ich für Option 2, weil ich MAP halten muss.

Answer 2

Ihr JSON enthält eine große Anzahl verschiedener Felder. Es scheint über 1000 verschiedene Einträge in der Karte zu geben. Jeder dieser Einträge ist selbst eine Karte mit einem einzelnen Schlüssel/Wert-Paar. Diese Schlüssel scheinen alle ebenfalls zu variieren. das gibt Ihnen mehr als 2000 Felder möglicherweise zu dokumentieren:

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

Diese Struktur macht es schwierig zu dokumentieren und ist auch ein starker Indikator dafür, dass es von Kunden schwer zu konsumieren sein wird. Im Idealfall würden Sie den JSON so umstrukturieren, dass jeder Eintrag dieselben Schlüssel hat und nur die Werte von Eintrag zu Eintrag variieren. So etwas wie dies, zum Beispiel:

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

Dies würde bedeuten, dass Sie nur eine Handvoll Felder zu dokumentieren:

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

Wenn das nicht möglich ist, dann höre ich auf zu versuchen, das Antwortfelder-Snippet zu verwenden, um die Struktur der Antwort zu dokumentieren. Stattdessen sollten Sie seine Struktur manuell in Ihrer Asciidoctor-Hauptdatei beschreiben.