docs: add documentation for sqs (#53)

timonback · web-flow · commit 350accf95d2d · 2023-09-25T10:22:37.000+02:00
* docs: add documentatino for sqs

* docs: Add 'Auto-generated' to vocab

* Update accept.txt
diff --git a/.github/styles/Vocab/Springwolf/accept.txt b/.github/styles/Vocab/Springwolf/accept.txt
@@ -2,6 +2,7 @@
 AMQP
 APIs
 auto-detect
+Auto-detected
 auto-detected
 auto-detection
 auto-generated
@@ -14,4 +15,4 @@ Netlify
 objectmapper
 Springfox
 Springwolf
-UI
+UI
diff --git a/docs/behind-the-scenes.md b/docs/behind-the-scenes.md
@@ -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.
 
@@ -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.
diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md
@@ -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`
 
@@ -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.
diff --git a/docs/configuration/documenting-consumers.md b/docs/configuration/documenting-consumers.md
@@ -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.
 
@@ -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.
 
diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md
@@ -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.
 
@@ -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)
@@ -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
-
-
diff --git a/docs/introduction/supported-protocols.md b/docs/introduction/supported-protocols.md
@@ -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
diff --git a/docs/quickstart.md b/docs/quickstart.md
@@ -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
 
@@ -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:
@@ -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
