Affects: Current and older doc

This is a doc enhancement request that I am also volunteering to write.

The current WebClient doc does not discuss how the Spring Framework uses Jackson to do the binding. It just says it does it and show the example of a Bean which has a 1:1 mapping to the receiving JSON. It would be nice to have an example and discussion like RESTTemplate does since WebClient seems to follow the same binding behavior.

https://spring.io/guides/gs/consuming-rest/ in the "Fetching a REST Resource" section.

Comment From: rstoyanchev

Can you clarify which WebClient doc you mean and which RestTemplate one has the right info?

Or do you mean the "Consuming a RESTful Web Service" guide in which case you can open an issue at https://github.com/spring-guides/gs-consuming-rest.

Comment From: thesteve0

Hey Rossen - There is no particular page in the Spring Doc that shows the consumption pattern of the JSON body -> Java Objects. The closest page in the official docs would be here https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html#webflux-client-retrieve

I don't see any Guides or Tutorials for WebFlux. So in the end there is no official documentation that I can find about how WebClient uses Jackson to instantiate and populate Java Objects.

I pointed out that guide because I think it does a nice job of explaining how the marshalling of JSON works in RestTemplate, and I would like something similar for webclient.

I spent days searching and trying out different streaming patterns to filter the JSON attributes per document in the body because there was no WebClient documentation available that explained the marshalling. I went deep into the stream stuff, which was interesting but not very fruitful. It was only when I found the RestTemplate doc that showed an example without mapping all the JSON attributes to the Object fields that I had a hint how it might work. So I decided to try the same pattern as in the RestTemplate example and cross my fingers that it would work. In the end it did and it would have made my entire problem take 5 minutes to read the doc and do the code rather than the days of streaming stuff I dug around in.

Long story short - I really like that section in the RestTemplate guide and want some of our official doc to show this for WebClient.

Comment From: thesteve0

Here is the example of the response type I want to show https://github.com/thesteve0/bootscraper/blob/16ec57324aa8e0d22e7c55353d8d49a6bb3268c6/src/main/java/com/molw/bootscraper/sources/DigiCurrencyFetcher.java#L42

With the quote object being defined with the ability to ignore json attributes not defined in the object https://github.com/thesteve0/bootscraper/blob/main/src/main/java/com/molw/bootscraper/data/Quote.java#L5

Comment From: bclozel

I think we should completely revisit the dedicated spring.io guide to have that aspect covered. I'll work on a PR to improve things there.

I'm not sure the reference documentation is the best place for that.

Comment From: thesteve0

Thanks @bclozel. Yeah I wasn't quite sure where to put it. Let me know if you would like me to help contribute

Comment From: rstoyanchev

Thanks for the feedback.

FWIW the reference docs isn't meant to be a tutorial. Those are different types of documentation. That said I'm still a little unsure what exactly you're missing and if we can improve the reference docs. These two look the same:

https://github.com/thesteve0/bootscraper/blob/16ec57324aa8e0d22e7c55353d8d49a6bb3268c6/src/main/java/com/molw/bootscraper/sources/DigiCurrencyFetcher.java#L42 https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html#webflux-client-retrieve

There is also the section on codecs including Jackson that I don't konw if you've come across: https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html#webflux-codecs

For the ignore attribute, I'm wondering if that is required given that our Jackson2ObjectMapperBuilder turns off the DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES.

In any case, I'm not saying there isn't room for improvement, and having your feedback on changes that Brian makes to the getting started guide would be appreciated. Likewise, have a look around the reference docs and feel free to make a more concrete proposal of what can be said in addition and where.

Comment From: bclozel

I've pushed changes to the guide, now using a Greeting POJO: it's serialized to JSON by a Controller and deseriazed by a WebClient. As Rossen mentioned, the "fail on unknown properties" is disabled by default in Spring so we might not need to cover that aspect.

Comment From: bclozel

I'm closing this issue as this has been taken care of in the guides (see previous comment).