Refactor Spring Boot documentation and spring-boot-examples

[salaboy]

Describe the proposal

The Spring Boot documentation provides a high-level introduction to using Dapr through the Dapr Spring Boot Starter and Dapr Spring Boot Starter Tests, which heavily integrate with Testcontainers.

Currently, the spring-boot-examples/ directory has three applications:

• Producer: To demonstrate basic APIs such as PubSub and StateStore integrated with Spring
• Consumer: To demonstrate subscriptions, but also to demonstrate how to test these scenarios.
• Workflow: Showing some basic workflow patterns

The aim of these examples is to provide concrete application examples that Spring Boot developers can understand and copy. The goal is not to provide simple/hello world examples on how to use the Dapr APIs, as this is already covered in the examples/ directory.

To improve the documentation and guides that target Spring Boot developers, the examples should cover:

1. PubSub (pubsub directory): move the producer and consumer apps to this directory
2. Service To Service Invocations (service-to-service): create an example that shows Service to Service invocation integrated with RestTemplate and Microcks for testing
3. Workflows (workflows): This should include, simple workflow app (simple-workflow), workflow app with PubSub (event-workflow), workflow patterns (patterns), which should include examples from this repository too (https://github.com/diagrid-labs/workflow-patterns-spring-boot) , Spring AI examples related to workflows (spring-ai) , Observability and workflows (observability)

The Spring Boot documentation should be updated to cover the following sections (https://docs.dapr.io/developing-applications/sdks/java/spring-boot/):

• Basics, dependencies, injection, basic information about using Dapr and testing with Testcontainers
• PubSub section, which includes the description of the refactored PubSub example (https://docs.dapr.io/developing-applications/sdks/java/spring-boot/#using-spring-messaging-for-producing-and-consuming-events)
• Service to Service Invocation, to cover a newly created example
• Workflows section (https://docs.dapr.io/developing-applications/sdks/java/spring-boot/#using-dapr-workflows-with-spring-boot) expanded with patterns, examples, Spring AI and observability
• Reference links to presentations and online resources

On top of this, we should highlight the Spring Boot integration at the top of the Java SDK page: https://docs.dapr.io/developing-applications/sdks/java/, so folks reaching this page can jump straight to Spring Boot instead of looking into the plain Java approach.

[salaboy]

@dapr/approvers-java-sdk @dapr/maintainers-java-sdk please add comments/suggestions on what else we should improve for Spring Boot developers.

[javier-aliaga]

I totally agree, but also I would like to reconsider how our tests/examples strategy.

[salaboy]

@javier-aliaga maybe we need to create a separate proposal for that. I would be happy to move the Spring Boot examples to a separate repo for example.

[cicoyle]

For this section:

Workflows (workflows): This should include, simple workflow app (simple-workflow), workflow app with PubSub (event-workflow), workflow patterns (patterns), which should include examples from this repository too (https://github.com/diagrid-labs/workflow-patterns-spring-boot) , Spring AI examples related to workflows (spring-ai) , Observability and workflows (observability)

Clarification question: Do you mean to have the following directories?

• spring-boot-examples/workflows/simple-workflow
• spring-boot-examples/workflows/event-workflow
• spring-boot-examples/workflows/patterns
• spring-boot-examples/workflows/spring-ai
• spring-boot-examples/workflows/observability

I am all for that 🎉

---

Re: the docs - We currently have the following:

Could we tab inwards from SpringBoot Integration on the left pane and have a Getting started section where most of what we have now goes into, then add tabs for pubsub, service invocation, and workflows?

Meaning something like this:

What are your thoughts on that? This would clean up having the springboot integration docs page being a catch all page in the docs and enable users to click it and see how to get started with it and use the respective APIs (pubsub/workflows/etc) from the left pane and keep it a bit cleaner while aligning with the other SDKs where on the left we traditionally have the Dapr APIs.

---

re: highlighting the Spring Boot Integration, I agree with you and think we could do something like how the Actors has this indent to highlight other docs:

---

re: reconsider how our tests/examples strategy

I am open to a proposal for this.

[salaboy]

Based on feedback provided by @msfussell I would recommend the following structure for the docs:

• Java
  • Overview (https://docs.dapr.io/developing-applications/sdks/java/) explaining the different alternatives (Spring Boot, Quarkus and plain Java). This should be simple and just contain links to the following sections.
  • Getting started for Spring Boot Developers
    • Maven/Gradle dependencies and Dependency Injection
    • Using Tescontainers for local development
    • DaprMessagingTemplate + PubSub Example
    • Dapr Workflows and Spring Boot
      • Basic workflow example
      • Workflow patterns with Spring Boot
      • Multi App Spring Boot example
    • Spring Boot references (blog posts, videos)
    • Other sections (to be created on a second iteration)
  • Getting started for Quarkus Developers (to be created on a second iteration)
  • Getting started for Java Developers
    • "Existing sections under Java today"

This structure will enable us to expand into different ecosystems and topics, while prioritizing Spring Boot developers.

[salaboy]

@dapr/maintainers-java-sdk @dapr/approvers-java-sdk please feel free to comment on this, as I am planning to start working on this very soon.