Skip to content

Commit abf338f

Browse files
timonbacktimonback
authored
Docs/0.16.0 release (#62)
* Document springwolf-generic-binding addon * Remove dependency swagger-inflector * deprecate AsyncApiDocket bean
1 parent f24e63d commit abf338f

File tree

7 files changed

+72
-43
lines changed

7 files changed

+72
-43
lines changed

‎docs/behind-the-scenes.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,9 @@ The `ChannelItem` contains the `Message` for the subscribe and/or publish operat
3333
When the scanners scan and build the result, they also extract the payload type.
3434
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.
3535

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.
36+
Using `swagger-core` any class can be converted into a OpenApi schema.
37+
The schema is used in the AsyncApi document.
38+
Additionally, Springwolf generates an example JSON based on the provided schema.
3839

3940
By using `swagger-parser`, all the `@Schema` and other swagger annotations are supported as well as `@JsonProperty` through the use of the objectmapper.
4041

‎docs/configuration/configuration.md‎

Lines changed: 25 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@ import CodeConfigurationAsyncApiDocket from '!!raw-loader!./snippets/_configurat
1111

1212
There are 2 ways to configure Springwolf which can't be combined:
1313

14-
1. `application.properties`, which is simple and moves all configuration to this file and annotations
14+
1. `application.properties`, which is simple and moves all configuration to this file and uses annotations
1515
2. (deprecated) `AsyncApiDocket`, which allows adding producers and consumers via code (instead of annotations)
1616

1717
<Tabs>
1818
<TabItem value="application.properties" label="application.properties" default>
1919
Add the following to the spring application.properties file.
2020
<CodeBlock language="properties">{CodeConfigurationProperties}</CodeBlock>
2121
</TabItem>
22-
<TabItem value="AsyncApiDocket" label="AsyncApiDocket">
22+
<TabItem value="AsyncApiDocket" label="AsyncApiDocket (deprecated)">
2323
Add a AsyncApiDocket bean to the spring context.
2424
<CodeBlock language="java">{CodeConfigurationAsyncApiDocket}</CodeBlock>
2525
</TabItem>
@@ -59,29 +59,29 @@ As with the `Info` object, all provided fields will be present in the generated
5959

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

62-
| Property Name | Default Value | Description |
63-
|----------------------------------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------|
64-
| `springwolf.enabled` | `true` | Allows to enable/disable Springwolf at one central place. |
65-
| `springwolf.init-mode` | `fail_fast` | Springwolf initializes during start up with `fail_fast` or in the `background` after the application has started. |
66-
| `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.* |
67-
| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. |
68-
| `springwolf.use-fqn` | `false` | Use fully qualified names for the schema classes. It's recommended and required for publishing, but deactivated due to backwards compatibility |
69-
| `springwolf.scanner.consumer-data.enabled` | `true` | Enable scanner to find consumers defined in `AsyncApiDocket`. |
70-
| `springwolf.scanner.producer-data.enabled` | `true` | Enable scanner to find producers defined in `AsyncApiDocket`. |
71-
| `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. |
72-
| `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. |
73-
| **AMQP** | | |
74-
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications* |
75-
| `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. |
76-
| **Kafka** | | |
77-
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce Kafka messages from the UI. *Note that this has security implications* |
78-
| `springwolf.plugin.kafka.publishing.producer` | `null` | Configure the Kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer` |
79-
| `springwolf.plugin.kafka.scanner.kafka-listener.enabled` | `true` | Enable scanner to find methods annotated with `@KafkaListener`. |
80-
| **SNS** | | |
81-
| `springwolf.plugin.sns.publishing.enabled` | `false` | Allow (anyone) to produce SNS messages from the UI. *Note that this has security implications* |
82-
| **SQS** | | |
83-
| `springwolf.plugin.sqs.publishing.enabled` | `false` | Allow (anyone) to produce SQS messages from the UI. *Note that this has security implications* |
84-
| `springwolf.plugin.sqs.scanner.sqs-listener.enabled` | `true` | Enable scanner to find methods annotated with `@SqsListener`. |
62+
| Property Name | Default Value | Description |
63+
|----------------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
64+
| `springwolf.enabled` | `true` | Allows to enable/disable Springwolf at one central place. |
65+
| `springwolf.init-mode` | `fail_fast` | Springwolf initializes during start up with `fail_fast` or in the `background` after the application has started. |
66+
| `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.* |
67+
| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. |
68+
| `springwolf.use-fqn` | `false` | Use fully qualified names for the schema classes. It's recommended and **required for publishing**, but deactivated due to backwards compatibility |
69+
| `springwolf.scanner.consumer-data.enabled` | `true` | Enable scanner to find consumers defined in `AsyncApiDocket`. |
70+
| `springwolf.scanner.producer-data.enabled` | `true` | Enable scanner to find producers defined in `AsyncApiDocket`. |
71+
| `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. |
72+
| `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. |
73+
| **AMQP** | | |
74+
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications* |
75+
| `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. |
76+
| **Kafka** | | |
77+
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce Kafka messages from the UI. *Note that this has security implications* |
78+
| `springwolf.plugin.kafka.publishing.producer` | `null` | Configure the Kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer` |
79+
| `springwolf.plugin.kafka.scanner.kafka-listener.enabled` | `true` | Enable scanner to find methods annotated with `@KafkaListener`. |
80+
| **SNS** | | |
81+
| `springwolf.plugin.sns.publishing.enabled` | `false` | Allow (anyone) to produce SNS messages from the UI. *Note that this has security implications* |
82+
| **SQS** | | |
83+
| `springwolf.plugin.sqs.publishing.enabled` | `false` | Allow (anyone) to produce SQS messages from the UI. *Note that this has security implications* |
84+
| `springwolf.plugin.sqs.scanner.sqs-listener.enabled` | `true` | Enable scanner to find methods annotated with `@SqsListener`. |
8585

8686

8787

‎docs/configuration/documenting-consumers.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ For these use-cases, Springwolf provides additional ways to explicitly add them
1111

1212
To document consumers, either:
1313
- add the `@AsyncListener` annotation or
14-
- declare the `ConsumerData` object as part of the `AsyncApiDocket` or
14+
- (deprecated) declare the `ConsumerData` object as part of the `AsyncApiDocket` or
1515
- rely on the auto-detection of `@KafkaListener`, `@RabbitListener`, `@SqsListener`
1616

1717
You are free to use all options together. Per channel and operation, first `ConsumerData` is used, then `@AsyncListener` and last the auto-detected annotations.
@@ -21,7 +21,7 @@ You are free to use all options together. Per channel and operation, first `Cons
2121
The `@AsyncListener` annotation is added to the method of the listeners and extracts the payload from its arguments.
2222
Additional fields can be documented.
2323

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

2626
Below is an example to demonstrate the annotation:
2727
```java

‎docs/configuration/documenting-producers.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Because producers are also an important part of AsyncAPI, Springwolf provides a
1010

1111
To document producers, either:
1212
- add the `@AsyncPublisher` annotation or
13-
- declare the `ProducerData` object as part of the `AsyncApiDocket`
13+
- (deprecated) declare the `ProducerData` object as part of the `AsyncApiDocket`
1414

1515
You are free to use all options together. Per channel and operation, first `ProducerData` is used, then `@AsyncPublisher`.
1616

@@ -19,7 +19,7 @@ You are free to use all options together. Per channel and operation, first `Prod
1919
The `@AsyncPublisher` annotation is added to the method of the publisher and extracts the payload from its arguments.
2020
Additional fields can be documented.
2121

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

2424
Below is an example to demonstrate the annotation:
2525
```java

‎docs/faq.md‎

Lines changed: 22 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -49,9 +49,31 @@ Publishing messages from the UI is disabled by default due to security concerns.
4949
Springwolf doesn't offer authentication nor authorization, anyone can publish messages to (production) channels.
5050
5151
Check the [configuration](configuration/configuration.md) to enable this feature.
52+
Be sure to enable fully qualified names ([`use-fqn`](configuration/configuration.md)) as well.
5253
5354
Spring Security allows to limit access to authorized users.
5455
56+
### Consumers are detected multiple times (with different payloads)
57+
58+
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
59+
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
60+
61+
Springwolf uses on scanners to find all consumer and producers in your application.
62+
Most likely two scanners found your consumer/producer each.
63+
See [configuration](configuration/configuration.md) to disable scanners.
64+
65+
### Only one of multiple classes with the same name (different package) is detected
66+
67+
Enable the fully qualified class name (FQN) option (`springwolf.use-fqn=true`) so that Springwolf uses the FQN internally.
68+
69+
### How to migrate from the deprecated `AsyncApiDocket` bean to Spring properties
70+
71+
1. `consumers` and/or `producers` defined in the `AsyncApiDocket` have to be converted to the `@AsyncListener` and/or `@AsyncPublisher` annotation approach.
72+
See the [Consumers](configuration/documenting-consumers.md) and [Producers](configuration/documenting-producers.md) page on how to map the properties.
73+
2. Map all entries of the docket to its Spring properties equivalent.
74+
The Spring properties equivalent start with `springwolf.docket.`.
75+
Example: The title within the info object is `springwolf.docket.info.title=my title`
76+
5577
### Is Spring Boot 2.X supported
5678
5779
You can use an older version of Springwolf, which is build to support Spring Boot 2.X.
@@ -93,13 +115,3 @@ from the given `apiDocsUrl` and store it in the `outputDir` and with the given `
93115

94116
If your application is unable to start up with the `bootRun` task, see if [customBootRun](https://github.com/springdoc/springdoc-openapi-gradle-plugin#customization)
95117
properties can help you.
96-
97-
### Consumers are detected multiple times (with different payloads)
98-
99-
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
100-
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
101-
102-
Springwolf uses on scanners to find all consumer and producers in your application.
103-
Most likely two scanners found your consumer/producer each.
104-
See [configuration](configuration/configuration.md) to disable scanners.
105-

‎docs/introduction/introduction.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ View the [live demo](https://demo.springwolf.dev) of Springwolf in action.
1919
Also, the demos of the
2020
[AMQP](https://amqp.demo.springwolf.dev),
2121
[Spring Cloud Stream](https://cloud-stream.demo.springwolf.dev),
22-
[Kafka](https://kafka.demo.springwolf.dev)
23-
[SNS](https://sns.demo.springwolf.dev)
22+
[Kafka](https://kafka.demo.springwolf.dev),
23+
[SNS](https://sns.demo.springwolf.dev),
2424
[SQS](https://sqs.demo.springwolf.dev)
2525
example projects are available.
2626

‎docs/introduction/supported-protocols.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,22 @@ Using [`@AsyncListener`](../configuration/documenting-consumers.md) and [`@Async
3030

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

33+
### `springwolf-generic-binding` add-on
34+
The `springwolf-generic-binding` add-on allows to document any binding.
35+
This includes bindings not supported by Springwolf, but also any custom fields not part of the AsyncApi specification.
36+
37+
```java
38+
@AsyncPublisher(...)
39+
@AsyncGenericOperationBinding(
40+
type = "custom-protocol-binding",
41+
fields = {
42+
"internal-field=customValue",
43+
"nested.key=nestedValue"})
44+
public void sendMessage(AnotherPayloadDto msg) {
45+
// publish message
46+
}
47+
```
48+
3349
[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
3450
[cloud-stream]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example
3551
[kafka]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example

0 commit comments

Comments
 (0)