Add support for RestTemplate

[hadjiski]

According to https://docs.spring.io/spring-restdocs/docs/current/reference/html5/ the following frameworks are supported: Spring MVC’s test framework, Spring WebFlux’s WebTestClient or REST Assured 3

Many component tests though are using just simple RestTemplate, without having the need to add any of the dependencies mentioned above. Now just to use restdocs those component tests must be changed to use let's say rest assured 3.

Would it be possible to add restdocs support for RestTemplate usage?

[wilkinsona]

I think it might be possible to support RestTemplate, but I don't think it's worth the initial engineering effort or the ongoing maintenance cost. Spring Framework's WebTestClient is the preferred, modern replacement for RestTemplate and, as you've noted above, it's already supported by REST Docs. Thanks anyway for the suggestion.

[hadjiski]

@wilkinsona "WebTestClient is a replacement for RestTemplate" since when? I did not know about that. Can u point me to an article or documentation to read more about this replacement and why was needed? Would gladly update our tests.

[wilkinsona]

Sorry, replacement probably wasn't quite the right word. RestTemplate is still part of Spring Framework 5. However, WebClient and WebTestClient are the preferred alternatives now.

[hadjiski]

Got it, but can u point me to an article or documentation explaining how and why WebTestClient is the preferable option over RestTemplate. Thanks

[wilkinsona]

Sorry, I'm not aware of such an article.

[mspiess]

Any chance to reconsider this?
RestTemplate does not seem to go away any time soon.
This could also support the new RestClient with its static method create(RestTemplate).

[wilkinsona]

Never say never but at this time I am yet to be convinced that it is worth the effort both in terms of the initial development and ongoing maintenance.

From what I have seen, tests that use an HTTP server are far less common than those that use mock web infrastructure. This also shows in the download numbers for REST Docs' existing modules with spring-restdocs-mockmvc having over 6x the downloads of spring-restdocs-restassured. IMO, RestAssured is a better option that either RestTemplate or the new RestClient for testing as it has a specific test focus and provides numerous methods that ease the testing of an HTTP-based API.

I think that spring-projects/spring-framework#31275 is worth keeping an eye on. If a new RestTestClient API that is similar to WebTestClient was added to Spring Framework it could be an interesting option for REST Docs to support.

[mspiess]

Thanks for pointing me to spring-projects/spring-framework#31275! I will definitely keep an eye on it.
I'd just like a way to generate docs from integration tests, without having to include WebFlux or a third-party dependency.
I just assumed that a lot of the effort for supporting RestTemplate and a potential RestTestClient would be shared, as I've read that RestClient uses RestTemplate infrastructure, but from your comment I gather that that's not (necessarily) the case.