How do you use Spring RestDocs to document the fields of WebFlux responses?

Question

I have an API that serves up responses as Flux and Mono which in turn provides a JSON payload as a Server Send Event.

I am also using Spring RestDocs to document the contents of that payload. These are generated in a WebFluxTest and an

I am able to generate a simple ResponseBody snippet using PayloadDocumentation.responseBody(), but when I try to describe the fields using field descriptors...

@WebFluxTest
@AutoConfigureRestDocs
@ContextConfiguration(classes = ArticleHandler.class)
class HandlerTest { 
...

    @Test
    void testGetArticle() {
        webClient.get()
                .uri("/articles/{id}", "article-id")
                .exchange()
                .expectStatus().isOk().expectBody().consumeWith(
                        document("article", PayloadDocumentation.responseFields(fieldWithPath("id")
                        .type(JsonFieldType.STRING)
                        .description("Unique ID for blog article")));
    }
}

I get the following failing test:

[Fatal Error] :1:1: Content is not allowed in prolog.

Cannot handle text/event-stream;charset=UTF-8 content as it could not be parsed as JSON or XML
org.springframework.restdocs.payload.PayloadHandlingException: Cannot handle text/event-stream;charset=UTF-8 content as it could not be parsed as JSON or XML
    at org.springframework.restdocs.payload.ContentHandler.forContentWithDescriptors(ContentHandler.java:69)
    at org.springframework.restdocs.payload.AbstractFieldsSnippet.createModel(AbstractFieldsSnippet.java:157)
    at org.springframework.restdocs.snippet.TemplatedSnippet.document(TemplatedSnippet.java:78)
    at org.springframework.restdocs.generate.RestDocumentationGenerator.handle(RestDocumentationGenerator.java:191)
    at org.springframework.restdocs.webtestclient.WebTestClientRestDocumentation.lambda$document$0(WebTestClientRestDocumentation.java:77)
    at org.springframework.test.web.reactive.server.DefaultWebTestClient$DefaultBodyContentSpec.lambda$consumeWith$3(DefaultWebTestClient.java:564)
    at org.springframework.test.web.reactive.server.ExchangeResult.assertWithDiagnostics(ExchangeResult.java:206)
    at org.springframework.test.web.reactive.server.DefaultWebTestClient$DefaultBodyContentSpec.consumeWith(DefaultWebTestClient.java:564)
    at com.project.blog.article.HandlerTest.testGetArticle(HandlerTest.java:62)

Are there any way that I can document the objects emitted in my text/event-stream payload?

Answer 1

Edit: For reference, here is the full class in "action": https://github.com/michael-simons/neo4j-from-the-jvm-ecosystem/blob/master/tck/src/test/java/org/neo4j/examples/jvm/tck/TckTest.java#L221-L257

I followed Andy's advice and implemented a preprocessor like this:

import static org.springframework.restdocs.operation.preprocess.Preprocessors.preprocessResponse;
import static org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath;
import static org.springframework.restdocs.payload.PayloadDocumentation.requestFields;
import static org.springframework.restdocs.payload.PayloadDocumentation.responseFields;


import org.springframework.restdocs.operation.preprocess.ContentModifyingOperationPreprocessor;

class Whatever {

    @Test
    @DisplayName("GET /api/movies")
    void verifyGetListOfMovies(@Autowired WebTestClient webclient) {
    
        var movies = webclient.get().uri("/movies")
            .exchange()
            .expectStatus().isOk()
            .expectHeader().value(HttpHeaders.CONTENT_TYPE,
                s -> {
                    var mediaType = MediaType.parseMediaType(s);
                    var compatibleMediaTypeReturned = mediaType.isCompatibleWith(MediaType.TEXT_EVENT_STREAM) ||
                                                      mediaType.isCompatibleWith(MediaType.APPLICATION_JSON);
                    assertThat(compatibleMediaTypeReturned).isTrue();
                })
            .expectBodyList(Movie.class)
            .consumeWith(document("movies", preprocessResponse(new ContentModifyingOperationPreprocessor(
                    (bytes, mediaType) -> {
                        var result = new StringBuilder().append("[");
                        try (var scanner = new Scanner(new ByteArrayInputStream(bytes), mediaType.getCharset()).useDelimiter("(\r?\n){2}")) {
                            while (scanner.hasNext()) {
                                String statement = scanner.next().trim().replaceAll("^data: *", "").trim();
                                if (statement.isEmpty()) {
                                    continue;
                                }
                                result.append(statement).append(",");
                            }
                        }
                        result.replace(result.length() - 1, result.length(), "]");
                        return result.toString().getBytes(mediaType.getCharset());
                    })
            ), responseFields(
                fieldWithPath("born").description("The year in which the person was born."),
                fieldWithPath("name").description("The name of the person."),
                fieldWithPath("id").description("The neo4j internal id."))
            ))
            .returnResult()
            .getResponseBody();
    }
}