Skip to content

Commit

Permalink
docs: add documentation for sqs (#53)
Browse files Browse the repository at this point in the history
* docs: add documentatino for sqs

* docs: Add 'Auto-generated' to vocab

* Update accept.txt
  • Loading branch information
timonback authored Sep 25, 2023
1 parent 65b926c commit 350accf
Show file tree
Hide file tree
Showing 7 changed files with 41 additions and 27 deletions.
3 changes: 2 additions & 1 deletion .github/styles/Vocab/Springwolf/accept.txt
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
AMQP
APIs
auto-detect
Auto-detected
auto-detected
auto-detection
auto-generated
Expand All @@ -14,4 +15,4 @@ Netlify
objectmapper
Springfox
Springwolf
UI
UI
4 changes: 2 additions & 2 deletions docs/behind-the-scenes.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,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, Kafka) are supported through plugins.
The different protocol (AMQP, Kafka, SQS) 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 All @@ -44,4 +44,4 @@ They follow the same plugin model.

## Putting it all together
The `AsyncApiService` collects all the channels, schemas and general info and builds the AsyncApi document.
The controller access this services to serve the document to the UI.
The controller access this services to serve the document to the UI.
7 changes: 6 additions & 1 deletion docs/configuration/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ There are 2 ways to configure Springwolf which can't be combined:

It's recommended to structure the project such that all consumers and producers (classes containing listener/producer methods) are in the same package - it's not mandatory, and if they're scattered across multiple packages, just provide the highest in hierarchy package that contains all classes.

The base package will be scanned for classes containing `@Component` annotated classes (that includes `@Service` annotated classes) for methods annotated with `@KafkaListener`, `@RabbitListener`, `@AsyncListener`, `@AsyncPublisher`, etc.
The base package will be scanned for classes containing `@Component` annotated classes (that includes `@Service` annotated classes) for methods annotated with `@KafkaListener`, `@RabbitListener`, `@SqsListener`, `@AsyncListener`, `@AsyncPublisher`, etc.

### `id`

Expand Down Expand Up @@ -75,6 +75,11 @@ The following table contains additional properties that can be specified in the
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce Kafka messages from the UI. *Note that this has security implications* |
| `springwolf.plugin.kafka.publishing.producer` | `null` | Configure the Kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer` |
| `springwolf.plugin.kafka.scanner.kafka-listener.enabled` | `true` | Enable scanner to find methods annotated with `@KafkaListener`. |
| **SQS** | | |
| `springwolf.plugin.sqs.publishing.enabled` | `false` | Allow (anyone) to produce SQS messages from the UI. *Note that this has security implications* |
| `springwolf.plugin.sqs.scanner.sqs-listener.enabled` | `true` | Enable scanner to find methods annotated with `@SqsListener`. |



[identifier]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#A2SIdString.
[info]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#infoObject.
Expand Down
6 changes: 3 additions & 3 deletions docs/configuration/documenting-consumers.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ For these use-cases, Springwolf provides additional ways to explicitly add them
To document consumers, either:
- add the `@AsyncListener` annotation or
- declare the `ConsumerData` object as part of the `AsyncApiDocket` or
- rely on the auto-detection of `@KafkaListener`, `@RabbitListener`
- rely on the auto-detection of `@KafkaListener`, `@RabbitListener`, `@SqsListener`

You are free to use all options together. Per channel and operation, first `ConsumerData` is used, then `@AsyncListener` and last the auto-detected annotations.

Expand Down Expand Up @@ -172,8 +172,8 @@ The above Kafka `ConsumerData` simplifies to the following `KafkaConsumerData`:
```


## Option 3: `@KafkaListener`, `@RabbitListener`
The `@KafkaListener` and `@RabbitListener` annotations are detected automatically.
## Option 3: `@KafkaListener`, `@RabbitListener`, `@SqsListener`
The `@KafkaListener`, `@RabbitListener`, `@SqsListener` annotations are detected automatically.
There is nothing more to do.
Use the other options if the provided documentation is insufficient.

Expand Down
5 changes: 2 additions & 3 deletions docs/introduction/introduction.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ sidebar_position: 10
API Documentation is an important part of every project and product, but can be painful to maintain manually.
Spring Boot projects have great solutions for auto-generated documentation for REST APIs to overcome this pain (such as Springfox, or springdoc-openapi).

However, until now there were no solutions for asynchronous APIs (such as Kafka, AMQP etc.). Springwolf aims to solve this and provides auto-generated documentation for asynchronous APIs built in Spring Boot.
However, until now there were no solutions for asynchronous APIs (such as AMQP, Kafka, SQS, etc.). Springwolf aims to solve this and provides auto-generated documentation for asynchronous APIs built in Spring Boot.

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.

Expand All @@ -20,6 +20,7 @@ Also, the demos of the
[AMQP](https://amqp.demo.springwolf.dev),
[Spring Cloud Stream](https://cloud-stream.demo.springwolf.dev),
[Kafka](https://kafka.demo.springwolf.dev)
[SQS](https://sqs.demo.springwolf.dev)
example projects are available.

![Springwolf publishing demo](/img/demo.gif)
Expand All @@ -44,5 +45,3 @@ By simply adding Springwolf dependency to your project you will automatically ge
- An endpoint returning an AsyncAPI document describing your asynchronous API.
- A web UI for convenient use by your developers, QA or clients of your asynchronous API.
- An easy way to publish messages to your asynchronous API with a click of a button


29 changes: 23 additions & 6 deletions docs/introduction/supported-protocols.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,32 @@ sidebar_position: 15

# Supported Protocols

| Protocol | Annotation | Example Project | Latest Plugin 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 | | [`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) |
| 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) |
Besides auto-detection of protocols (native support),
any protocol can be defined using Springwolf custom annotations `@AsyncListener` and `@AsyncPublisher`.

## Native Support

The following protocols are supported natively:

| Protocol | Auto-detected annotations | Example Project | Latest Plugin 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) |
| 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) |
| 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) |

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.

Please [open an issue](https://github.com/springwolf/springwolf-core/issues/new) if you want a protocol to be supported.

## Any protocol

Using [`@AsyncListener`](../configuration/documenting-consumers.md) and [`@AsyncPublisher`](../configuration/documenting-producers.md) any protocol can be documented, although the binding in the AsyncApi document will remain empty.

The protocols with native support come along with a `@_ProtocolName_Binding` annotation to define protocol specific properties.

[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
[kafka]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example
[cloud-stream]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example
[kafka]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example
[sqs]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-sqs-example
14 changes: 3 additions & 11 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ import CodeSpringwolfMaven from '!!raw-loader!./snippets/_springwolf_maven.xml';

# Quickstart

*The following instructions are for Kafka services - but AMQP services configuration is almost same. Check out the [example project for complete examples](https://github.com/timonback/springwolf-core/tree/master/springwolf-examples).*
*The following instructions are for Kafka services - but AMQP services configuration is almost same. Check out the [example project for complete examples](https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples).*

## 1. Add dependencies

Expand All @@ -24,12 +24,7 @@ Add the following dependencies:
</TabItem>
</Tabs>

Latest version:
- ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-amqp?color=green&label=springwolf-amqp&style=plastic)
- ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-cloud-stream?color=green&label=springwolf-cloud-stream&style=plastic)
- ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-kafka?color=green&label=springwolf-kafka&style=plastic)
- ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-ui?color=green&label=springwolf-ui&style=plastic)

Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-core?color=green&label=springwolf&style=plastic)
## 2. Configure properties

Add the following to your application.properties:
Expand Down Expand Up @@ -57,8 +52,5 @@ If you configured a different context path in your application, make sure to pre
## 4. Next steps

- Read an elaborated tutorial on Baeldung at https://www.baeldung.com/java-spring-doc-asyncapi-springwolf
- Check out the example projects:
- AMQP: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
- Spring-cloud-stream: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example
- Kafka: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example
- Check out the [supported protocols and example projects](introduction/supported-protocols)
- Dive deeper on the next pages

0 comments on commit 350accf

Please sign in to comment.