Skip to content

Commit 96bae2c

Browse files
timonbacktimonback
committed
docs: Documenting consumers with annotation
1 parent f64fe18 commit 96bae2c

File tree

5 files changed

+137
-37
lines changed

5 files changed

+137
-37
lines changed

‎docs/configuration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ The following table contains additional properties that can be specified in the
6666

6767
| Property Name | Default Value | Description |
6868
|----------------------------------------------| ------------- |---------------------------------------------------------------------------------------------------------------------------|
69-
| `springwolf.enabled` | `true` | Allows to disable springwolf at one central place. |
69+
| `springwolf.enabled` | `true` | Allows to enable/disable springwolf at one central place. |
7070
| `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.* |
7171
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce amqp messages from the UI. *Note that this has security implications* |
7272
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce kafka messages from the UI. *Note that this has security implications* |

‎docs/documenting-consumers.md‎

Lines changed: 113 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,11 +4,91 @@ sidebar_position: 5
44

55
# Documenting Consumers
66

7-
Sometimes projects are configured in a way that makes Springwolf unable to automatically locate consumers (They don't have the `@KafkaListener`, `@RabbitListener`, `@AsyncSubscriber` annotations on the consuming methods).
7+
Springwolf comes with build-in support to auto-detect listeners of supported protocols.
88

9-
Because there is still immense value in documenting the consumers, Springwolf provides a way to explicitly add them to the generated document, by declaring them in the `AsyncApiDocket` using the `ConsumerData` object.
9+
Sometimes projects are configured in a way that makes Springwolf unable to automatically locate consumers or the generated documentation is insufficient.
10+
For these use-cases, Springwolf provides additional ways to explicitly add them to the generated document.
1011

11-
## `ConsumerData`
12+
To document consumers, either:
13+
- add the `@AsyncSubscriber` annotation or
14+
- declare the `ConsumerData` object as part of the `AsyncApiDocket` or
15+
- rely on the auto-detection of `@KafkaListener`, `@RabbitListener`
16+
17+
You are free to use all options together. Per channel and operation, first `ConsumerData` is used, then `@AsyncSubscriber` and last the auto-detected annotations.
18+
19+
## Option 1: `@AsyncSubscriber`
20+
21+
The `@AsyncSubscriber` annotation is added to the method of the listeners and extracts the payload from its arguments.
22+
Additional fields can be documented.
23+
24+
The protocol operation binding is configured via `@AmqpAsyncOperationBinding` or `@KafkaAsyncOperationBinding`, which has to be on the same method.
25+
26+
Below is an example to demonstrate the annotation:
27+
```java
28+
@KafkaListener
29+
@AsyncSubscriber(operation = @AsyncOperation(
30+
channelName = "example-consumer-topic",
31+
description = "Optional. Customer uploaded an example payload",
32+
headers = @AsyncOperation.Headers(
33+
schemaName = "SpringKafkaDefaultHeaders",
34+
values = {
35+
@AsyncOperation.Headers.Header(
36+
name = DEFAULT_CLASSID_FIELD_NAME,
37+
description = "Spring Type Id Header",
38+
value = "io.github.stavshamir.springwolf.example.dtos.ExamplePayloadDto"
39+
),
40+
}
41+
)
42+
))
43+
@KafkaAsyncOperationBinding
44+
public void receiveMessage(ExamplePayloadDto msg) {
45+
// process
46+
}
47+
```
48+
49+
:::note
50+
Springwolf only finds methods that are within the `base-package`.
51+
:::
52+
53+
### Channel Name
54+
55+
The channel name (or topic name in case of Kafka) - this is the name that will be used to subscribe to messages to by the UI.
56+
57+
### Description
58+
59+
Optional. The description allows for human-friendly text to verbosely explain the _message_, like specific domain, what the topic is used for and which data it contains.
60+
61+
### Payload Type
62+
63+
The class object of the payload that will be consumed from this channel.
64+
If not specified, it is extracted from the method arguments.
65+
66+
### Header
67+
68+
Optional. The headers describing the metadata of the payload.
69+
70+
### `@AmqpAsyncOperationBinding`
71+
72+
Associate this operation with amqp, see [operation-binding] for details.
73+
74+
```java
75+
@AmqpAsyncOperationBinding(cc = "example-topic-routing-key")
76+
```
77+
78+
### `@KafkaAsyncOperationBinding`
79+
80+
Associate this operation with kafka, see [operation-binding] for details.
81+
82+
```java
83+
@KafkaAsyncOperationBinding(
84+
bindingVersion = "1",
85+
clientId = "foo-clientId",
86+
groupId = "#{'foo-groupId'}"
87+
)
88+
```
89+
90+
91+
## Option 2: `ConsumerData`
1292

1393
:::tip
1494
Use specific ConsumerData types `AmqpConsumerData` & `KafkaConsumerData` for protocol specific attributes
@@ -49,7 +129,7 @@ Optional. The description allows for human-friendly text to verbosely explain th
49129

50130
### Binding
51131

52-
This property is used to discriminate the consumer's protocol and provide protocol-specific properties (see [Operation Binding Object](https://www.asyncapi.com/docs/specifications/v2.0.0#operationBindingsObject)).
132+
This property is used to discriminate the producer's protocol and provide protocol-specific properties (see [operation-binding])).
53133

54134
### Payload Type
55135

@@ -62,7 +142,7 @@ By default, `AsyncHeaders.NOT_DOCUMENTED` is used to indicate that no explicit h
62142
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.
63143

64144

65-
## `AmqpConsumerData`
145+
### `AmqpConsumerData`
66146

67147
The above Kafka `ConsumerData` equivalent in `AmqpConsumerData`:
68148
```java
@@ -75,9 +155,29 @@ The above Kafka `ConsumerData` equivalent in `AmqpConsumerData`:
75155
.build();
76156
```
77157

158+
### `KafkaConsumerData`
159+
160+
The above Kafka `ConsumerData` simplifies to the following `KafkaConsumerData`:
161+
```java
162+
KafkaConsumerData exampleConsumerData = KafkaConsumerData.kafkaConsumerDataBuilder()
163+
.topicName("example-consumer-topic")
164+
.description("Optional. Customer uploaded an example payload")
165+
.payloadType(ExamplePayloadDto.class)
166+
.headers(AsyncHeaders.NOT_USED)
167+
.build();
168+
```
169+
170+
171+
## Option 3: `@KafkaListener`, `@RabbitListener`
172+
The `@KafkaListener` and `@RabbitListener` annotations are detected automatically.
173+
There is nothing more to do.
174+
Use the other options if the provided documentation is insufficient.
175+
176+
177+
## AMQP Parameters
78178
### Queue Name (Channel Name)
79179

80-
The queue name that will be used to publish messages to by the UI.
180+
The queue name that will be used to consume messages from.
81181

82182
### Description
83183

@@ -95,26 +195,12 @@ The routing key used when publishing a message.
95195

96196
The class object of the payload that will be consumed from this channel.
97197

98-
### Example
99198

100-
See a full example [here](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java).
101-
102-
103-
## `KafkaConsumerData`
104-
105-
The above Kafka `ConsumerData` simplifies to the following `KafkaConsumerData`:
106-
```java
107-
KafkaConsumerData exampleConsumerData = KafkaConsumerData.kafkaConsumerDataBuilder()
108-
.topicName("example-consumer-topic")
109-
.description("Optional. Customer uploaded an example payload")
110-
.payloadType(ExamplePayloadDto.class)
111-
.headers(AsyncHeaders.NOT_USED)
112-
.build();
113-
```
199+
## Kafka Parameters
114200

115201
### Topic Name (Channel Name)
116202

117-
The topic name that will be used to publish messages to by the UI.
203+
The topic name that will be used to consume messages from.
118204

119205
### Description
120206

@@ -130,7 +216,10 @@ The Kafka headers describing the metadata of the payload, more details in the ge
130216

131217
The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the spring-kafka dependency.
132218

219+
## Examples
133220

134-
### Example
221+
- [AMQP Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
222+
- [Cloud Stream Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-cloud-stream-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
223+
- [Kafka Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
135224

136-
See a full example [here](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java).
225+
[operation-binding]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#operationBindingsObject

‎docs/documenting-producers.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,18 @@ Unlike consumers which are defined declaratively with an annotation, producers a
88

99
Because producers are also an important part of Async APIs, Springwolf provides a way to explicitly add them to the generated document.
1010

11-
To document them, either:
11+
To document producers, either:
1212
- add the `@AsyncPublisher` annotation or
1313
- declare the `ProducerData` object as part of the `AsyncApiDocket`
1414

15+
You are free to use all options together. Per channel and operation, first `ProducerData` is used, then `@AsyncPublisher`.
16+
1517
## Option 1: `@AsyncPublisher`
1618

1719
The `@AsyncPublisher` annotation is added to the method of the publisher and extracts the payload from its arguments.
1820
Additional fields can be documented.
1921

20-
The protocol binding is configured via `@AmqpAsyncOperationBinding` or `@KafkaAsyncOperationBinding`, which has to be on the same method.
22+
The protocol operation binding is configured via `@AmqpAsyncOperationBinding` or `@KafkaAsyncOperationBinding`, which has to be on the same method.
2123

2224
Below is an example to demonstrate the annotation:
2325
```java
@@ -76,12 +78,11 @@ Associate this operation with kafka, see [operation-binding] for details.
7678

7779
```java
7880
@KafkaAsyncOperationBinding(
79-
bindingVersion = "1",
80-
clientId = "foo-clientId",
81-
groupId = "#{'foo-groupId'}"
81+
bindingVersion = "1"
8282
)
8383
```
8484

85+
8586
## Option 2: `ProducerData`
8687

8788
:::tip
@@ -149,8 +150,6 @@ The above Kafka `ProducerData` equivalent in `AmqpProducerData`:
149150
.build();
150151
```
151152

152-
153-
154153
### `KafkaProducerData`
155154

156155
The above Kafka `ProducerData` simplifies to the following `KafkaProducerData`:
@@ -163,6 +162,7 @@ The above Kafka `ProducerData` simplifies to the following `KafkaProducerData`:
163162
.build();
164163
```
165164

165+
166166
## AMQP Parameters
167167
### Queue Name (Channel Name)
168168

@@ -184,6 +184,7 @@ The routing key used when publishing a message.
184184

185185
The class object of the payload that will be published to this channel.
186186

187+
187188
## Kafka Parameters
188189

189190
### Topic Name (Channel Name)
@@ -204,9 +205,10 @@ The Kafka headers describing the metadata of the payload, more details in the ge
204205

205206
The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the spring-kafka dependency.
206207

207-
### Example
208+
## Examples
208209

209210
- [AMQP Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
211+
- [Cloud Stream Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-cloud-stream-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
210212
- [Kafka Example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java)
211213

212-
[operation-binding]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#operationBindingsObject
214+
[operation-binding]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#operationBindingsObject

‎docs/faq.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ If not, check
2121
2. if static assets are being served. See the code below:
2222
```java
2323
@Configuration
24-
public class WebConfig implements WebMvcConfigurer {
24+
public class WebConfig implements WebMvcConfigurer {
2525

2626
@Override
2727
public void addResourceHandlers(ResourceHandlerRegistry registry) {
@@ -34,8 +34,17 @@ public class WebConfig implements WebMvcConfigurer {
3434

3535
Taken from [Discord Chat](https://discord.com/channels/950375987475005471/950375988217409548/1051909821848363038)
3636

37+
### Unable to publish message from the UI
38+
39+
Publishing messages from the UI is disabled by default due to security concerns.
40+
Springwolf does not offer authentication nor authorization, anyone can publish messages to (production) channels.
41+
42+
Check the [configuration](configuration.md) to enable this feature.
43+
44+
Spring Security allows to limit access to authorized users.
45+
3746
## Usage Patterns
3847

3948
### How to access the generated documentation within java?
4049

41-
Use the `AsyncApiService` to access the generated documentation.
50+
Use the `AsyncApiService` to access the generated documentation.

‎docs/introduction.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ public class ExampleConsumer {
3535
```
3636

3737
By simply adding Springwolf dependency and a short configuration class to your project you will automatically get:
38-
- An endpoint returning an asyncapi document (similar to an openapi document) describing your async API.
38+
- An endpoint returning an asyncapi document describing your async API.
3939
- A web UI for convenient use by your developers, QA or clients of your async API.
4040
- An easy way to publish messages to your async API with a click of a button
4141

0 commit comments

Comments
 (0)