You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/behind-the-scenes.md
+8-8Lines changed: 8 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,10 +10,10 @@ The following paragraphs describe how Springwolf works internally.
10
10
When the Spring Boot application is started, Springwolf uses its scanners to find defined consumers and producers within the application.
11
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
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).
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
15
16
-
When publishing is enabled, the user can publish a message through the ui to another endpoint.
16
+
When publishing is enabled, the user can publish a message through the UI to another endpoint.
17
17
From there, Springwolf forwards the message to the protocol specific producer.
18
18
19
19
## Plugins
@@ -24,7 +24,7 @@ When building own scanner plugins, your plugin will need to implement the `Chann
24
24
25
25
## Scanners
26
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.
27
+
When the same channel/topic is found multiple times, it's merged as well.
28
28
29
29
The result is a [`ChannelItem`](https://www.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject).
30
30
The `ChannelItem` contains the `Message` for the subscribe and/or publish operation.
@@ -33,15 +33,15 @@ The `ChannelItem` contains the `Message` for the subscribe and/or publish operat
33
33
When the scanners scan and build the result, they also extract the payload type.
34
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
35
36
-
Using `swagger-parser` any class can be converted into a OpenAPI schema.
37
-
The schema is then used to serialized it into an example json for the AsyncAPI document.
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
38
39
39
By using `swagger-parser`, all the `@Schema` and other swagger annotations are supported as well as `@JsonProperty` through the use of the objectmapper.
40
40
41
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.
42
+
ModelConverters provide a way to improve documentation for classes, which can't be modified, for example because they're part of an external library.
43
43
They follow the same plugin model.
44
44
45
45
## Putting it all together
46
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.
47
+
The controller access this services to serve the document to the UI.
Copy file name to clipboardExpand all lines: docs/configuration/configuration.md
+13-13Lines changed: 13 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,12 +4,12 @@ sidebar_position: 30
4
4
import Tabs from '@theme/Tabs';
5
5
import TabItem from '@theme/TabItem';
6
6
import CodeBlock from '@theme/CodeBlock';
7
-
import CodeConfigurationProperties from '!!raw-loader!./snippets/_configuration_properties.md';
8
-
import CodeConfigurationAsyncApiDocket from '!!raw-loader!./snippets/_configuration_asyncApiDocket.md';
7
+
import CodeConfigurationProperties from '!!raw-loader!./snippets/_configuration_properties.properties';
8
+
import CodeConfigurationAsyncApiDocket from '!!raw-loader!./snippets/_configuration_asyncApiDocket.java';
9
9
10
10
# Configuration
11
11
12
-
There are 2 ways to configure Springwolf which cannot be combined:
12
+
There are 2 ways to configure Springwolf which can't be combined:
13
13
14
14
1.`application.properties`, which is simple and moves all configuration to this file and annotations
15
15
2. (deprecated) `AsyncApiDocket`, which allows adding producers and consumers via code (instead of annotations)
@@ -27,31 +27,31 @@ There are 2 ways to configure Springwolf which cannot be combined:
27
27
28
28
## Properties
29
29
30
-
### basePackage (required)
30
+
### `basePackage` (required)
31
31
32
-
It is recommended to structure the project such that all consumers and producers (classes containing listener/producer methods) are in the same package - it is not mandatory, and if they are scattered across multiple packages, just provide the highest in hierarchy package that contains all of them.
32
+
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.
33
33
34
34
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.
35
35
36
-
### id
36
+
### `id`
37
37
38
38
The `Identifier` value represents a unique universal identifier of the application. See [Identifier][identifier].
39
39
40
-
### default-content-type
40
+
### `default-content-type`
41
41
42
42
A string representing the default content type to use when encoding/decoding a message's payload. See [Default Content Type][default-content-type]
43
43
44
-
### Info (required)
44
+
### `Info` (required)
45
45
46
46
The `Info` object provides metadata about the API (see [Info Object][info]).
47
47
48
48
All provided fields will be present in the generated document, but not all will be displayed in the UI.
49
49
50
-
### Server
50
+
### `Server`
51
51
52
52
The `Server` object provides metadata the can help the reader understand the protocol, version, login details and more (see [Server Object][server]).
53
53
54
-
An AsyncAPI document can contain more than one server, but it is not common.
54
+
An AsyncAPI document can contain more than one server, but it's not common.
55
55
56
56
As with the `Info` object, all provided fields will be present in the generated document, but not all will be displayed in the UI.
57
57
@@ -69,11 +69,11 @@ The following table contains additional properties that can be specified in the
69
69
|`springwolf.scanner.async-listener.enabled`|`true`| Enable scanner to find methods annotated with `@AsyncListener`. |
70
70
|`springwolf.scanner.async-publisher.enabled`|`true`| Enable scanner to find methods annotated with `@AsyncPublisher`. |
71
71
|**AMQP**|||
72
-
|`springwolf.plugin.amqp.publishing.enabled`|`false`| Allow (anyone) to produce amqp messages from the UI. *Note that this has security implications*|
72
+
|`springwolf.plugin.amqp.publishing.enabled`|`false`| Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications*|
73
73
|`springwolf.plugin.amqp.scanner.rabbit-listener.enabled`|`true`| Enable scanner to find methods annotated with `@RabbitListener`. |
74
74
|**Kafka**|||
75
-
|`springwolf.plugin.kafka.publishing.enabled`|`false`| Allow (anyone) to produce kafka messages from the UI. *Note that this has security implications*|
76
-
|`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.publishing.enabled`|`false`| Allow (anyone) to produce Kafka messages from the UI. *Note that this has security implications*|
76
+
|`springwolf.plugin.kafka.publishing.producer`|`null`| Configure the Kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer`|
77
77
|`springwolf.plugin.kafka.scanner.kafka-listener.enabled`|`true`| Enable scanner to find methods annotated with `@KafkaListener`. |
Associate this operation with kafka, see [operation-binding] for details.
80
+
Associate this operation with Kafka, see [operation-binding] for details.
81
81
82
82
```java
83
83
@KafkaAsyncOperationBinding(
@@ -91,7 +91,7 @@ Associate this operation with kafka, see [operation-binding] for details.
91
91
## Option 2: `ConsumerData` (deprecated)
92
92
93
93
:::note
94
-
Must use configuration via `AsyncApiDocket` and cannot use `application.properties`.
94
+
Must use configuration via `AsyncApiDocket` and can't use `application.properties`.
95
95
:::
96
96
97
97
Below is an example of describing a Kafka consumer:
@@ -143,7 +143,7 @@ The class object of the payload that will be consumed from this channel.
143
143
144
144
Optional. The headers describing the metadata of the payload.
145
145
By default, `AsyncHeaders.NOT_DOCUMENTED` is used to indicate that no explicit header documentation exists.
146
-
Use `AsyncHeaders` to add your custom headers, use `AsyncHeaders.NOT_USED` if you do not use headers and `AsyncHeadersForCloudEventsBuilder` if your events follow the CloudEvent specification.
146
+
Use `AsyncHeaders` to add your custom headers, use `AsyncHeaders.NOT_USED` if you don't use headers and `AsyncHeadersForCloudEventsBuilder` if your events follow the CloudEvent specification.
147
147
148
148
149
149
### `AmqpConsumerData`
@@ -218,7 +218,7 @@ The class object of the payload that will be consumed from this channel.
218
218
219
219
The Kafka headers describing the metadata of the payload, more details in the generic ConsumerData.
220
220
221
-
The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the spring-kafka dependency.
221
+
The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the `spring-kafka` dependency.
@@ -74,17 +76,18 @@ public class ExamplePayloadDto {
74
76
}
75
77
}
76
78
```
79
+
<!-- vale on -->
77
80
78
81
:::note
79
82
The `@AsyncMessage.description` field will always override the `@Schema` description if provided
80
83
:::
81
84
82
-
For a full example, take a look at [ExamplePayloadDto.java in springwolf-amqp-example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/stavshamir/springwolf/example/amqp/dtos/ExamplePayloadDto.java)
85
+
For a full example, take a look at [ExamplePayloadDto.java in `springwolf-amqp-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/stavshamir/springwolf/example/amqp/dtos/ExamplePayloadDto.java)
83
86
84
87
## Custom ModelConverters
85
88
86
89
Additionally, custom `ModelConverters` are supported.
87
90
These are needed when swagger is unable to extract a schema from a class.
88
91
89
92
One example is `javax.money.MonetaryAmount`.
90
-
Adding a model converter is demoed in [springwolf-add-ons/springwolf-common-model-converters](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-common-model-converters)
93
+
Adding a model converter is demoed in [`springwolf-add-ons/springwolf-common-model-converters`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-common-model-converters)
0 commit comments