Dokumentieren Byte [] Antwort in Spring Rest Docs

Question

Ich bin ein API erstellen und dokumentieren mit Spring Rest Docs (1.1.1.RELEASE) und es gibt eine API, die ein Bild als Byte-Array zurückgibt.

Ich muss den Antworttyp in REST-Dokumenten beschreiben. Ich bin nicht sicher, wie dies FieldDescriptor mit getan werden kann

Wenn ich versuche:

//get mock byte array 
byte[] attachment = "Hello".getBytes(); 

FieldDescriptor[] contentFields = new FieldDescriptor[] { 
      fieldWithPath("").type(byte[].class) 
        .description("bytes of the attachment ")}; 

    when(serviceMock.getImage("fe329638007b4ea3b2a5")).thenReturn(attachment); 

    this.mockMvc 
      .perform(RestDocumentationRequestBuilders.get("/api/v1/contents/{contentId}/images", "fe329638007b4ea3b2a5")) 
      .andExpect(status().isOk()).andDo(document("{method-name}", 
        pathParameters(parameterWithName("contentId").description("The id of the Content")), 
        responseFields(contentFields))); 

    verify(serviceMock, times(1)).getImage("fe329638007b4ea3b2a5"); 
    verifyNoMoreInteractions(serviceMock); 

ich die folgenden Fehler

org.springframework.restdocs.payload.PayloadHandlingException: com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'Hello': was expecting ('true', 'false' or 'null') 
at [Source: [B@13866865; line: 1, column: 11] 
at org.springframework.restdocs.payload.JsonContentHandler.readContent(JsonContentHandler.java:86) 
at org.springframework.restdocs.payload.JsonContentHandler.findMissingFields(JsonContentHandler.java:52) 
at org.springframework.restdocs.payload.AbstractFieldsSnippet.validateFieldDocumentation(AbstractFieldsSnippet.java:152) 
at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:100) 
at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:64) 
at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:196) 
at org.springframework.restdocs.mockmvc.RestDocumentationResultHandler.handle(RestDocumentationResultHandler.java:55) 
at org.springframework.test.web.servlet.MockMvc$1.andDo(MockMvc.java:177) 
at com.davita.comms.controller.CommsControllerTest.getThumbnailByContentId(CommsControllerTest.java:205) 
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 
at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) 
at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) 
at java.lang.reflect.Method.invoke(Method.java:497) 
at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:50) 
at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:12) 
at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:47) 
at org.junit.internal.runners.statements.InvokeMethod.evaluate(InvokeMethod.java:17) 
at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:26) 
at org.springframework.test.context.junit4.statements.RunBeforeTestMethodCallbacks.evaluate(RunBeforeTestMethodCallbacks.java:75) 
at org.springframework.test.context.junit4.statements.RunAfterTestMethodCallbacks.evaluate(RunAfterTestMethodCallbacks.java:86) 
at org.springframework.restdocs.JUnitRestDocumentation$1.evaluate(JUnitRestDocumentation.java:55) 
at org.junit.rules.RunRules.evaluate(RunRules.java:20) 
at org.springframework.test.context.junit4.statements.SpringRepeat.evaluate(SpringRepeat.java:84) 
at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:325) 
at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:252) 
at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.runChild(SpringJUnit4ClassRunner.java:94) 
at org.junit.runners.ParentRunner$3.run(ParentRunner.java:290) 
at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:71) 
at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:288) 
at org.junit.runners.ParentRunner.access$000(ParentRunner.java:58) 
at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:268) 
at org.springframework.test.context.junit4.statements.RunBeforeTestClassCallbacks.evaluate(RunBeforeTestClassCallbacks.java:61) 
at org.springframework.test.context.junit4.statements.RunAfterTestClassCallbacks.evaluate(RunAfterTestClassCallbacks.java:70) 
at org.junit.runners.ParentRunner.run(ParentRunner.java:363) 
at org.springframework.test.context.junit4.SpringJUnit4ClassRunner.run(SpringJUnit4ClassRunner.java:191) 
at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:86) 
at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38) 
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:459) 
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:670) 
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:382) 
at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:192) 

Gibt es bekommen eine Art und Weise in FieldDescriptor zu erwähnen, dass die zurückgegebenen Daten ist kein json, also macht es keinen sinn, einen pfad zu haben.

Gibt es eine andere Möglichkeit, dies ohne FieldDescriptors zu dokumentieren?

Answer 1

REST Docs unterstützt keine Dokumentation des Inhalts von binären Nutzdaten. Die Snippets für Anfrage- und Antwortfelder dienen zur Dokumentation der Struktur einer JSON- oder XML-Nutzlast.

Ich glaube nicht, dass Sie von der Verwendung von REST Docs profitieren, um die Tabelle zur Beschreibung Ihrer binären Antwort zu erstellen, da es nicht viel zu behaupten gibt. Jede Antwort kann als ein Byte [] behandelt werden, da eine Antwort in ihrer ursprünglichsten Form vorliegt. Zum Beispiel ist JSON ein Byte [] wie XML. Sie sind nur Byte-Arrays mit bestimmten Einschränkungen für ihren Inhalt.

Anstatt zu versuchen, REST Docs zu verwenden, um eine Tabelle zu generieren, um die binäre Antwort zu beschreiben, würde ich es einfach in Ihre .adoc Datei kodieren. Wenn Sie in Ihrem Test einige Behauptungen über den Inhalt der Antwort einfügen möchten, würde ich einige der MockMvc-Matcher verwenden. Sie könnten beispielsweise angeben, dass der Hauptteil der Antwort den Bytes entspricht, die Sie für die Rückgabe des Scheindiensts konfiguriert haben.