Документирование байта [] ответ в Spring Rest Docs

Question

Я создаю API и документирую его с помощью Spring Rest Docs (1.1.1.RELEASE), и есть api, который возвращает изображение в виде массива байтов.

Мне нужно описать тип ответа в документах REST. Я не знаю, как это можно сделать с помощью FieldDescriptor

Когда я пытаюсь:

//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); 

Я получаю ошибку ниже

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) 

Есть ли способ, чтобы упомянуть в FieldDescriptor, что возвращаемые данные не является json, поэтому нет смысла иметь путь.

Есть ли другой способ документировать это без FieldDescriptors?

Answer 1

REST Docs не имеет никакой поддержки для документирования содержимого бинарных данных. Фрагменты полей запроса и ответа предназначены для документирования структуры полезной нагрузки JSON или XML.

Я не думаю, что вы получаете большую пользу от использования REST Docs для генерации таблицы для описания вашего двоичного ответа, поскольку утверждать нечего. Любой ответ можно рассматривать как байт [], так как это ответ в самой сырой форме. Например, JSON является байтом [], как и XML. Они просто массивы байтов с особыми ограничениями на их содержимое.

Вместо того, чтобы пытаться использовать REST Docs для создания таблицы для описания двоичного ответа, я бы просто записал ее в файле .adoc. Если вы хотите включить некоторые утверждения в свой тест о содержании ответа, я бы использовал некоторые из макетов MockMvc. Например, вы могли бы утверждать, что тело ответа соответствует байтам, которые вы настроили для макетной службы.