Improve starter reference documentation

[Sam-Kruglov]

I'm pretty sure several years ago looking at whatever tech on spring boot's docs it would advise to pull certain starters. These days I don't see any mention of those starters anywhere except this simple table with 1 line descriptions.

For example, looking at how to set up JSR 303 Bean Validation, core docs only say I need "JSR-303 implementation (such as Hibernate validator)" on the classpath, then I gotta go their docs and it also says some sort of "Jakarta Expression Language" is also required but doesn't mention if Spring Boot requires it or not. After some digging, I found there's "spring-boot-starter-validation" that actually pulls Tomcat-specific EL dependency along with the Hibernate Validator.

Why don't the docs mention any of that? And that doesn't only apply to validation, I don't ever see any starters or dependencies or proper setup instructions for things. Another example with AOP Load-Time Weaving, I spent several days setting this up, some info was in javadocs, some was vaguely explained in the docs, and finally baeldung had the full setup documented after which it finally worked - although it was not about starters that time but still required dependencies aren't documented.

I see Spring push for their initializer which has all the starters but I only create a project once, after that I don't ever look at that. I could've sworn like 5 years ago the docs were explaining all that, what happened?

At this point, I might prefer going to baeldung instead of actual spring docs.

[philwebb]

I could've sworn like 5 years ago the docs were explaining all that, what happened?

Perhaps we've somehow lost something that was previously clearer in documentation. 5 years ago would be Spring Boot 2.2. The docs for that are available at https://docs.spring.io/spring-boot/docs/2.2.x/reference/htmlsingle/. Which parts were you remembering?

[Sam-Kruglov]

Ok, looking closer, it also had to do with what I was doing. I was mostly working with Web MVC and Data JPA. These particular spring boot docs did mention at lot of starters right in the docs. Comparing to the current versions, Data Access section of spring boot, does still mention the starters.

Now I am working on trying to setup AOP Load-Time Weaving and Bean Validation and both sections of the Framework as well as Boot do not mention any dependencies, even though there are some starters available.

For AOP LTW, it did mention that I needed spring-aspects but there is an AOP starter. I don't actually need AOP at all, so I ended up without the starter, I just want @Transactional and @Cacheable to work when called from the same instance. Also the docs weren't clear whether I needed to add a java agent or not, it says if I run tomcat then I don't, so I assumed since spring boot does that by default then I don't. But I actually do because I got errors saying class loader is incompatible, and in addition to the docs saying I needed spring-instrument, I also needed to add a second agent aspectjweaver - which both jars I had to figure out how to download and save via maven-dependency-plugin. I also couldn't make compile-time weaving to work with intellij&kotlin, it just built regular classes without weaving unless invoked from maven, so I went with load-time instead. Baeldung ended up most helpful while spring docs were confusing.

For Bean Validation, there are no mentions of which dependencies needed but there is a validation starter. That starter also brings in tomcat-embed-el which I'm not sure if needed, searching online seems to be related to JSP. Message interpolation works without it. Hibernate Validator also documents how to use their @ScriptAssert to run SpEL on the whole object to validate it but Spring doesn't even mention that and doesn't seem to have any pre-made config for it. Although it is specific to Hibernate Validator and not just JSR 303.

So I guess this ticket is to make sure every section of spring boot that requires setup should have a setup section that includes all the recommended dependencies and config changes. Right now some sections like I mentioned above and possibly others simply get right into how to use the thing without setting it up.