Skip to content

Commit 4d946c9

Browse files
timonbacktimonback
authored
Feat/documenting new release (#25)
* docs: #22: Document version for Spring Boot 2.X * docs: #20: Add scanner application.properties options * docs: Move supported protocols to top in sidebar * docs: FAQ: multiple channels detected * docs: Behind the scenes
1 parent 3000d82 commit 4d946c9

File tree

9 files changed

+96
-18
lines changed

9 files changed

+96
-18
lines changed

‎docs/behind-the-scenes.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
sidebar_position: 70
3+
---
4+
5+
# Behind the scenes
6+
7+
The following paragraphs describe how springwolf works internally.
8+
9+
## Big Picture
10+
When the Spring Boot application is started, springwolf uses its scanners to find defined consumers and producers within the application.
11+
Based on the results, the channels/topics are extracted including payload type and merged together into an [AsyncApi conform document](https://www.asyncapi.com/docs/reference/specification/v2.6.0).
12+
13+
The AsyncApi document is accessible an endpoint.
14+
When the springwolf ui is opened, the browser fetches the document and renders it (see demo).
15+
16+
When publishing is enabled, the user can publish a message through the ui to another endpoint.
17+
From there, springwolf forwards the message to the protocol specific producer.
18+
19+
## Plugins
20+
`springwolf-core` provides the base functionality to orchestrate the scanning and building of the AsyncApi document.
21+
The different protocol (AMQP, Kafka) are supported through plugins.
22+
These plugins are found through the Spring dependency injection functionality.
23+
When building own scanner plugins, your plugin will need to implement the `ChannelsScanner` interface.
24+
25+
## Scanners
26+
`springwolf-core` runs all scanners and merges the found results together into one AsyncApi document.
27+
When the same channel/topic is found multiple times, it is merged as well.
28+
29+
The result is a [`ChannelItem`](https://www.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject).
30+
The `ChannelItem` contains the `Message` for the subscribe and/or publish operation.
31+
32+
## Building an example payload
33+
When the scanners scan and build the result, they also extract the payload type.
34+
The payload is registered in the `SchemasService`, which allows to split the `Message` from the schema definition - within the AsyncApi doc a `$ref` references is used.
35+
36+
Using `swagger-inflector` any class can be converted into a OpenApi schema.
37+
This is used to instantiate an Example object with default values and serialized into an example json for the AsyncApi document.
38+
39+
By using `swagger-inflector`, all the `@Schema` and other swagger annotations are supported as well as `@JsonProperty` through the use of the objectmapper.
40+
41+
### ModelConverters
42+
ModelConverters provide a way to improve documentation for classes, which cannot be modified, for example because they are part of an external library.
43+
They follow the same plugin model.
44+
45+
## Putting it all together
46+
The `AsyncApiService` collects all the channels, schemas and general info and builds the AsyncApi document.
47+
The controller access this services to serve the document to the ui.

‎docs/configuration.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 3
2+
sidebar_position: 30
33
---
44
import Tabs from '@theme/Tabs';
55
import TabItem from '@theme/TabItem';
@@ -58,12 +58,21 @@ As with the `Info` object, all provided fields will be present in the generated
5858

5959
The following table contains additional properties that can be specified in the `application.properties` file:
6060

61-
| Property Name | Default Value | Description |
62-
|----------------------------------------------| ------------- |---------------------------------------------------------------------------------------------------------------------------|
63-
| `springwolf.enabled` | `true` | Allows to enable/disable springwolf at one central place. |
64-
| `springwolf.paths.docs` | `/springwolf/docs` | The path of the AsyncAPI document in JSON format. *Note that at the moment the UI will work only with the default value.* |
65-
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce amqp messages from the UI. *Note that this has security implications* |
66-
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce kafka messages from the UI. *Note that this has security implications* |
61+
| Property Name | Default Value | Description |
62+
|----------------------------------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------|
63+
| `springwolf.enabled` | `true` | Allows to enable/disable springwolf at one central place. |
64+
| `springwolf.paths.docs` | `/springwolf/docs` | The path of the AsyncAPI document in JSON format. *Note that at the moment the UI will work only with the default value.* |
65+
| `springwolf.scanner.consumer-data.enabled` | `true` | Enable scanner to find consumers defined in `AsyncApiDocket`. |
66+
| `springwolf.scanner.producer-data.enabled` | `true` | Enable scanner to find producers defined in `AsyncApiDocket`. |
67+
| `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. |
68+
| `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. |
69+
| **AMQP** | | |
70+
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce amqp messages from the UI. *Note that this has security implications* |
71+
| `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. |
72+
| **Kafka** | | |
73+
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce kafka messages from the UI. *Note that this has security implications* |
74+
| `springwolf.plugin.kafka.publishing.producer` | `null` | Configure the kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer` |
75+
| `springwolf.plugin.kafka.scanner.kafka-listener.enabled` | `true` | Enable scanner to find methods annotated with `@KafkaListener`. |
6776

6877
[info]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#infoObject.
6978
[server]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#serversObject

‎docs/documenting-consumers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 60
33
---
44

55
# Documenting Consumers

‎docs/documenting-producers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 64
33
---
44

55
# Documenting Producers

‎docs/documenting-schemas.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 68
33
---
44

55
import Tabs from '@theme/Tabs';

‎docs/faq.md‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 10
2+
sidebar_position: 80
33
---
44

55
# Frequently Asked Questions
@@ -43,6 +43,18 @@ Check the [configuration](configuration.md) to enable this feature.
4343

4444
Spring Security allows to limit access to authorized users.
4545

46+
### Is Spring Boot 2.X supported?
47+
48+
You can use an older version of springwolf, which is build to support Spring Boot 2.X.
49+
However, these versions do not get any updates.
50+
51+
Last versions to support Spring Boot 2.X:
52+
- springwolf-amqp:0.6.0
53+
- springwolf-cloud-stream:0.1.0
54+
- springwolf-core:0.6.0
55+
- springwolf-kafka:0.10.0
56+
- springwolf-ui:0.6.0
57+
4658
## Usage Patterns
4759

4860
### How to access the generated documentation within java?
@@ -72,3 +84,13 @@ from the given `apiDocsUrl` and store it in the `outputDir` and with the given `
7284

7385
If your application is unable to start up with the bootRun task, see if [customBootRun](https://github.com/springdoc/springdoc-openapi-gradle-plugin#customization)
7486
properties can help you.
87+
88+
### My consumers are detected multiple times (with different payloads)
89+
90+
When springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
91+
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
92+
93+
Springwolf uses on scanners to find all consumer and producers in your application.
94+
Most likely two scanners found your consumer/producer each.
95+
See [configuration](configuration/configuration.md) to disable scanners.
96+

‎docs/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 1
2+
sidebar_position: 10
33
---
44

55
# Introduction

‎docs/quickstart.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 2
2+
sidebar_position: 20
33
---
44
import Tabs from '@theme/Tabs';
55
import TabItem from '@theme/TabItem';
@@ -25,10 +25,10 @@ Add the following dependencies:
2525
</Tabs>
2626

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

3333
## Configuration properties
3434

‎docs/supported-protocols.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 6
2+
sidebar_position: 15
33
---
44

55
# Supported Protocols

0 commit comments

Comments
 (0)