Skip to content

Commit

Permalink
Docs/0.16.0 release (#62)
Browse files Browse the repository at this point in the history 
* Document springwolf-generic-binding addon

* Remove dependency swagger-inflector

* deprecate AsyncApiDocket bean
  • Loading branch information
@timonback
timonback authored Oct 29, 2023
1 parent f24e63d commit abf338f
Show file tree
Hide file tree
Showing 7 changed files with 72 additions and 43 deletions.
5 changes: 3 additions & 2 deletions docs/behind-the-scenes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,9 @@ The `ChannelItem` contains the `Message` for the subscribe and/or publish operat
When the scanners scan and build the result, they also extract the payload type.
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.

Using `swagger-inflector` any class can be converted into a OpenApi schema.
This is used to instantiate an Example object with default values and serialized into an example JSON for the AsyncApi document.
Using `swagger-core` any class can be converted into a OpenApi schema.
The schema is used in the AsyncApi document.
Additionally, Springwolf generates an example JSON based on the provided schema.

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

Expand Down
50 changes: 25 additions & 25 deletions docs/configuration/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,15 +11,15 @@ import CodeConfigurationAsyncApiDocket from '!!raw-loader!./snippets/_configurat

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

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

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

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

| Property Name | Default Value | Description |
|----------------------------------------------------------|--------------------|---------------------------------------------------------------------------------------------------------------------------|
| `springwolf.enabled` | `true` | Allows to enable/disable Springwolf at one central place. |
| `springwolf.init-mode` | `fail_fast` | Springwolf initializes during start up with `fail_fast` or in the `background` after the application has started. |
| `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.* |
| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. |
| `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 |
| `springwolf.scanner.consumer-data.enabled` | `true` | Enable scanner to find consumers defined in `AsyncApiDocket`. |
| `springwolf.scanner.producer-data.enabled` | `true` | Enable scanner to find producers defined in `AsyncApiDocket`. |
| `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. |
| `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. |
| **AMQP** | | |
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications* |
| `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. |
| **Kafka** | | |
| `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`. |
| **SNS** | | |
| `springwolf.plugin.sns.publishing.enabled` | `false` | Allow (anyone) to produce SNS messages from the UI. *Note that this has security implications* |
| **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`. |
| Property Name | Default Value | Description |
|----------------------------------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| `springwolf.enabled` | `true` | Allows to enable/disable Springwolf at one central place. |
| `springwolf.init-mode` | `fail_fast` | Springwolf initializes during start up with `fail_fast` or in the `background` after the application has started. |
| `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.* |
| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. |
| `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 |
| `springwolf.scanner.consumer-data.enabled` | `true` | Enable scanner to find consumers defined in `AsyncApiDocket`. |
| `springwolf.scanner.producer-data.enabled` | `true` | Enable scanner to find producers defined in `AsyncApiDocket`. |
| `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. |
| `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. |
| **AMQP** | | |
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications* |
| `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. |
| **Kafka** | | |
| `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`. |
| **SNS** | | |
| `springwolf.plugin.sns.publishing.enabled` | `false` | Allow (anyone) to produce SNS messages from the UI. *Note that this has security implications* |
| **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`. |



Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/documenting-consumers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,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
- (deprecated) declare the `ConsumerData` object as part of the `AsyncApiDocket` or
- 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.
Expand All @@ -21,7 +21,7 @@ You are free to use all options together. Per channel and operation, first `Cons
The `@AsyncListener` annotation is added to the method of the listeners and extracts the payload from its arguments.
Additional fields can be documented.

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

Below is an example to demonstrate the annotation:
```java
Expand Down
4 changes: 2 additions & 2 deletions docs/configuration/documenting-producers.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Because producers are also an important part of AsyncAPI, Springwolf provides a

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

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

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

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

Below is an example to demonstrate the annotation:
```java
Expand Down
32 changes: 22 additions & 10 deletions docs/faq.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,9 +49,31 @@ Publishing messages from the UI is disabled by default due to security concerns.
Springwolf doesn't offer authentication nor authorization, anyone can publish messages to (production) channels.
Check the [configuration](configuration/configuration.md) to enable this feature.
Be sure to enable fully qualified names ([`use-fqn`](configuration/configuration.md)) as well.
Spring Security allows to limit access to authorized users.
### Consumers are detected multiple times (with different payloads)
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
Springwolf uses on scanners to find all consumer and producers in your application.
Most likely two scanners found your consumer/producer each.
See [configuration](configuration/configuration.md) to disable scanners.
### Only one of multiple classes with the same name (different package) is detected
Enable the fully qualified class name (FQN) option (`springwolf.use-fqn=true`) so that Springwolf uses the FQN internally.
### How to migrate from the deprecated `AsyncApiDocket` bean to Spring properties
1. `consumers` and/or `producers` defined in the `AsyncApiDocket` have to be converted to the `@AsyncListener` and/or `@AsyncPublisher` annotation approach.
See the [Consumers](configuration/documenting-consumers.md) and [Producers](configuration/documenting-producers.md) page on how to map the properties.
2. Map all entries of the docket to its Spring properties equivalent.
The Spring properties equivalent start with `springwolf.docket.`.
Example: The title within the info object is `springwolf.docket.info.title=my title`
### Is Spring Boot 2.X supported
You can use an older version of Springwolf, which is build to support Spring Boot 2.X.
Expand Down Expand Up @@ -93,13 +115,3 @@ from the given `apiDocsUrl` and store it in the `outputDir` and with the given `

If your application is unable to start up with the `bootRun` task, see if [customBootRun](https://github.com/springdoc/springdoc-openapi-gradle-plugin#customization)
properties can help you.

### Consumers are detected multiple times (with different payloads)

When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.

Springwolf uses on scanners to find all consumer and producers in your application.
Most likely two scanners found your consumer/producer each.
See [configuration](configuration/configuration.md) to disable scanners.

4 changes: 2 additions & 2 deletions docs/introduction/introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ View the [live demo](https://demo.springwolf.dev) of Springwolf in action.
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)
[SNS](https://sns.demo.springwolf.dev)
[Kafka](https://kafka.demo.springwolf.dev),
[SNS](https://sns.demo.springwolf.dev),
[SQS](https://sqs.demo.springwolf.dev)
example projects are available.

Expand Down
16 changes: 16 additions & 0 deletions docs/introduction/supported-protocols.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,22 @@ Using [`@AsyncListener`](../configuration/documenting-consumers.md) and [`@Async

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

### `springwolf-generic-binding` add-on
The `springwolf-generic-binding` add-on allows to document any binding.
This includes bindings not supported by Springwolf, but also any custom fields not part of the AsyncApi specification.

```java
@AsyncPublisher(...)
@AsyncGenericOperationBinding(
type = "custom-protocol-binding",
fields = {
"internal-field=customValue",
"nested.key=nestedValue"})
public void sendMessage(AnotherPayloadDto msg) {
// publish message
}
```

[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-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
Expand Down

0 comments on commit abf338f

Please sign in to comment.