Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve documentation on wire-format #99

Merged
merged 1 commit into from
Nov 8, 2024
Merged

docs: improve documentation on wire-format #99

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/behind-the-scenes.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Loading