Eventuate Tram Springwolf (Async API) Support

This project is a Springwolf plugin for Eventuate Tram and Eventuate Sagas that documents Eventuate-based APIs using Async API.

In the same way that springdoc-openapi exposes a /v3/api-docs endpoint, this project exposes an /springwolf/docs endpoint that documents the Eventuate-based APIs.

An Eventuate project

This project is part of Eventuate, which is a microservices collaboration platform.

Getting started

Snapshot

To use Eventuate Tram Springwolf, add the following dependency to your project:

dependencies {
    implementation(platform("io.eventuate.platform:eventuate-platform-dependencies:$eventuatePlatformVersion"))

    runtimeOnly "io.eventuate.tram.springwolf:eventuate-tram-springwolf-support-starter"

Define these properties in application.properties:

springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0
springwolf.docket.base-package=io.eventuate.tram.spring.springwolf.someexample
springwolf.docket.scanner.async-listener.enabled=false

springwolf.docket.servers.eventuate-producer.protocol=eventuate-outbox
springwolf.docket.servers.eventuate-producer.host=${spring.datasource.url}
springwolf.docket.servers.eventuate-consumer.protocol=kafka
springwolf.docket.servers.eventuate-consumer.host=${eventuatelocal.kafka.bootstrap.servers}

Note: springwolf.docket.base-package needs to be set even though it is not used in the code.

Testing support

To use the testing support, add the following dependency to your project:

dependencies {
    testImplementation "io.eventuate.tram.springwolf:eventuate-tram-springwolf-support-testing"

You can then write a test that makes assertions about the generated Async API document:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
public class EventuateTramSpringWolfEventsTest {

  @LocalServerPort
  private int port;

  @BeforeEach
  public void setup() {
    RestAssured.port = port;
  }

  @Test
  public void shouldExposeSpringWolf() {
    AsyncApiDocument doc = AsyncApiDocument.getSpringWolfDoc();

    assertThat(doc.getVersion())
        .as("AsyncAPI version should be 3.0.0")
        .isEqualTo("3.0.0");

    doc.assertSendsMessage(...);
    doc.assertReceivesMessage(...);
    doc.assertReceivesMessage(...);
  }
...

Example Async API documentation

Here are some examples:

• Events publishing and handling - Describes the event message channels and their message formats (generated by EventuateTramSpringWolfEventsTest)

• Saga orchestration (command-sending) - Details the saga orchestration message channels and structures (generated by EventuateTramSpringWolfSagasTest)

• Command handling - Documents the command message channels and their message structures (generated by EventuateTramSpringWolfCommandsTest)

Example code

The development branches of the following projects use Eventuate Tram Springwolf:

• eventuate-tram-examples-customers-and-orders

• eventuate-tram-sagas-examples-customers-and-orders

Contributing

Contributions are welcome.

Please sign a contributor license agreement.