Skip to content

Commit

Permalink
docs: improve documentation on wire-format (#99)
Browse files Browse the repository at this point in the history
  • Loading branch information
@timonback
timonback authored Nov 8, 2024
1 parent 2a86325 commit 6a74775
Show file tree
Hide file tree
Showing 3 changed files with 26 additions and 22 deletions.
2 changes: 1 addition & 1 deletion docs/behind-the-scenes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ From there, Springwolf forwards the message to the protocol specific producer.
## Plugins

`springwolf-core` provides the base functionality to orchestrate the scanning and building of the AsyncAPI document.
The different protocol (AMQP, Cloud-Stream, JMS, Kafka, SNS, SQS, STOMP/WebSocket) are supported through plugins.
The [different protocol](./introduction/supported-protocols.md) are supported through plugins.
These plugins are found through the Spring dependency injection functionality.
When building own scanner plugins, your plugin will need to implement the `ChannelsScanner` interface.

Expand Down
14 changes: 2 additions & 12 deletions docs/introduction/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,21 +17,11 @@ However, until now there were no solutions for asynchronous APIs (such as AMQP,

Springwolf is compliant to [AsyncAPI](https://www.asyncapi.com), which brings the [swagger/OpenAPI](https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi) specification you know already from REST APIs into the world of event-driven architectures.

### Demo
## Demo

View the [live demo](https://demo.springwolf.dev) of Springwolf in action.

Also, the demos of the
[AMQP](https://amqp.demo.springwolf.dev),
[Spring Cloud Stream](https://cloud-stream.demo.springwolf.dev),
[JMS](https://jms.demo.springwolf.dev),
[Kafka](https://kafka.demo.springwolf.dev),
[SNS](https://sns.demo.springwolf.dev),
[SQS](https://sqs.demo.springwolf.dev),
[STOMP (WebSocket)](https://stomp.demo.springwolf.dev)
example projects are available.

![Springwolf publishing demo](/img/demo.gif)
[![Springwolf publishing demo](/img/demo.gif)](https://demo.springwolf.dev)

## What does it do

Expand Down
32 changes: 23 additions & 9 deletions docs/introduction/supported-protocols.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,16 +10,15 @@ any protocol can be defined using Springwolf custom annotations `@AsyncListener`
## Native Support

The following protocols are supported natively:

| Protocol | Auto-detected annotations | Example Project | Latest Plugin Version |
| Protocol + Demo | Auto-detected annotations | Example Project | Latest Version |
|-------------------|---------------------------------------------|-------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| AMQP (RabbitMQ) | `@RabbitListener` | [`springwolf-amqp-example`][amqp] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-amqp?color=green&label=springwolf-amqp&style=plastic) |
| Cloud Functions | `@Bean` (functional interface) | [`springwolf-cloud-stream`][cloud-stream] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-cloud-stream?color=green&label=springwolf-cloud-stream&style=plastic) |
| JMS | `@JmsListener` | [`springwolf-jms-example`][jms] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-jms?color=green&label=springwolf-jms&style=plastic) |
| Kafka | `@KafkaListener`, `@KafkaHandler` | [`springwolf-kafka-example`][kafka] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-kafka?color=green&label=springwolf-kafka&style=plastic) |
| SNS | | [`springwolf-sns-example`][sns] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sns?color=green&label=springwolf-sns&style=plastic) |
| SQS | `@SqsListener` | [`springwolf-sqs-example`][sqs] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sqs?color=green&label=springwolf-sqs&style=plastic) |
| STOMP (WebSocket) | `@MessageMapping`, `@SendTo`, `@SendToUser` | [`springwolf-stomp-example`][stomp] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-stomp?color=green&label=springwolf-stomp&style=plastic) |
| [AMQP (RabbitMQ)](https://amqp.demo.springwolf.dev) | `@RabbitListener` | [`springwolf-amqp-example`][amqp] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-amqp?color=green&label=springwolf-amqp&style=plastic) |
| [Cloud Functions](https://cloud-stream.demo.springwolf.dev) | `@Bean` (functional interface) | [`springwolf-cloud-stream`][cloud-stream] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-cloud-stream?color=green&label=springwolf-cloud-stream&style=plastic) |
| [JMS](https://jms.demo.springwolf.dev) | `@JmsListener` | [`springwolf-jms-example`][jms] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-jms?color=green&label=springwolf-jms&style=plastic) |
| [Kafka](https://kafka.demo.springwolf.dev) | `@KafkaListener`, `@KafkaHandler` | [`springwolf-kafka-example`][kafka] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-kafka?color=green&label=springwolf-kafka&style=plastic) |
| [SNS](https://sns.demo.springwolf.dev) | | [`springwolf-sns-example`][sns] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sns?color=green&label=springwolf-sns&style=plastic) |
| [SQS](https://sqs.demo.springwolf.dev) | `@SqsListener` | [`springwolf-sqs-example`][sqs] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sqs?color=green&label=springwolf-sqs&style=plastic) |
| [STOMP (WebSocket)](https://stomp.demo.springwolf.dev) | `@MessageMapping`, `@SendTo`, `@SendToUser` | [`springwolf-stomp-example`][stomp] | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-stomp?color=green&label=springwolf-stomp&style=plastic) |

Check out the example projects, which include a full `docker-compose` setup.
The examples are simple, easy to start with, good for testing and reproducing bugs.
Expand Down Expand Up @@ -52,6 +51,21 @@ The supported binding annotations are:
See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding)
:::

## Wire format (Data serialization)

Besides the classical JSON events, Springwolf has best-effort support for some other wire formats.

### Avro

[Avro](https://avro.apache.org) is supported out-of-the box and demoed in [kafka example](#native-support).

### Protobuf

[Protobuf](https://protobuf.dev) is demoed in [kafka example](#native-support).

To remove the fields generated by the Protobuf class generated, add a `ModelResolver` bean, which uses the `ProtobufModule` to your project.
See [ObjectMapperConfiguration](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/springwolf/examples/kafka/configuration/ObjectMapperConfiguration.java) for details.

[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
[cloud-stream]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example
[jms]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-jms-example
Expand Down

0 comments on commit 6a74775

Please sign in to comment.