Native support for Server-Sent Events and Streaming API endpoints

[sdeleuze]

Maybe Spring REST Docs could support natively Server-Sent Events endpoints, as supported in Spring Framework 4.2+ thanks to SseEmitter type, and global Streaming API support based on ResponseBodyEmitter type.

I am not sure yet about what that support would be, but for example Spring REST Docs could recognize SseEmitter return types, and generate a snippet with a curl command with text/event-streammedia type, handle the fact that some SSE endpoints never closes the connection (handle a timeout but not as an error?), and eventually provide Javascript code that would help people to use that endpoint in their application.

This issue is also intended to prepare support for Spring Web Reactive, which will provide first class support for streaming API via handler methods returning types like Flux<Foo> or Observable<Foo>. And unlike SseEmitter and ResponseBodyEmitter, these types will carry more type information within their Generic type.

[wilkinsona]

@sdeleuze What's the current state of MockMvc for testing controller methods that return SseEmitter or ResponseBodyEmitter?

[andrashatvani]

Any news on this?

[wilkinsona]

@andrashatvani Not really. We still think it's an idea worth exploring but haven't had the time to do so. If you have suggestions for how you'd like the support to look please let us know and perhaps we can kickstart something.

[rstoyanchev]

Test streaming responses in Spring MVC has been possible through the WebTestClient since Spring Framework 5.0 by running with a live server. In 5.3 it became possible to run WebTestClient against a MockMvc instance as well. I've just improved the docs on that including a sample https://github.com/spring-projects/spring-framework/issues/26687.

I think that Spring REST Docs can be used for streaming responses. For example something like this:

FluxExchangeResult<String> exchangeResult = this.webTestClient.get().uri("/")
        .exchange()
        .expectStatus().isOk()
        .returnResult(Person.class);

// Consume response
StepVerifier.create(result.getResponseBody())
        .expectNextCount(4)
        .thenCancel()
        .verify();

WebTestClientRestDocumentation.document("index").accept(exchangeResult);

In effect, let the response be tested and consumed first. Then it should be possible to access the response body content. Assuming this all works as expected, it should just be a matter of updating the reference docs with such guidance.