Chapter 7 Samples is quite lite on content, it just links to the samples directory on git repo. I propose adding the following sections to the Samples chapter.
- A short overview section describing what samples exist in the samples/ project
- Sample apps directory with an entry for each sample app.
This would have an entry for each sample app should include - a short 1 to 3 sentence description of what the sample app demonstrates, so that users can quickly find an example of what they are looking to do. - a link to the sample application source code to easily find the code
The samples directory can be nicely organized along into category to make discovery easier. Suggested categories are.
- Servlets
- Web Authentication
- Web Authorization
- Method Security
- Reactive
- Web Authentication
- Web Authorization
- Method Security
It is possible to generate the content for such a directory automatically, below are some approaches.
buildfile approach Each samples gradle build file can define a gradle task to write out an summary.adoc file, then the parent project can iterate the child projects call each of the generate summary tasks, and collect all the output into the summary chapter. With this approach as the samples are updated summary directory gets generated.
description.md approach each samples gets a new file called description.md or description.adoc that can be included from the samples chapter.
The build file approach can more easily tag and category the samples, and potentially can be leveraged to drop references to sample apps in different sections of the docs.
Comment From: rwinch
I like where you are going with this suggestion. However, it might be valuable to further split this up into
- Organize Samples
- Update documentation
- Automate Documentation
Could you please create separate tickets? We can re-purpose this as the ticket to "Update Documentation" step since that is what the title implies.
For Servlets we also need to consider is it XML, Java Config, Boot, Kotlin, etc. We want all source code in the docs to be illustrated by a sample and be able to point to a complete sample so all code can be contextualized.
Comment From: spring-projects-issues
If you would like us to look at this issue, please provide the requested information. If the information is not provided within the next 7 days this issue will be closed.
Comment From: asaikali
I have added two new issues spring-projects/spring-security-samples#62 and spring-projects/spring-security#8328 I don't know the samples well enough to know how best to organize them, so the descriptions are pretty light.
Comment From: matthewadams
FYI, there's a fantastic example that I think you should steal/include that combines Boot, WebFlux, Security & Kotlin coroutines at https://github.com/soasada/kotlin-coroutines-webflux-security. We hit this problem and docs on the preceding tech stack are practically nonexistent.