diff --git a/docs/behind-the-scenes.md b/docs/behind-the-scenes.md index ef4c6f6..f5e8f41 100644 --- a/docs/behind-the-scenes.md +++ b/docs/behind-the-scenes.md @@ -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. diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md index 19c3728..536f837 100644 --- a/docs/configuration/configuration.md +++ b/docs/configuration/configuration.md @@ -11,7 +11,7 @@ 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) @@ -19,7 +19,7 @@ There are 2 ways to configure Springwolf which can't be combined: Add the following to the spring application.properties file. {CodeConfigurationProperties} - + Add a AsyncApiDocket bean to the spring context. {CodeConfigurationAsyncApiDocket} @@ -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`. | diff --git a/docs/configuration/documenting-consumers.md b/docs/configuration/documenting-consumers.md index 5f88acb..7a3880c 100644 --- a/docs/configuration/documenting-consumers.md +++ b/docs/configuration/documenting-consumers.md @@ -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. @@ -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 diff --git a/docs/configuration/documenting-producers.md b/docs/configuration/documenting-producers.md index 144b464..0b6217e 100644 --- a/docs/configuration/documenting-producers.md +++ b/docs/configuration/documenting-producers.md @@ -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`. @@ -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 diff --git a/docs/faq.md b/docs/faq.md index c575ac5..1f22ce3 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -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. @@ -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. - diff --git a/docs/introduction/introduction.md b/docs/introduction/introduction.md index 837fcce..36340fb 100644 --- a/docs/introduction/introduction.md +++ b/docs/introduction/introduction.md @@ -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. diff --git a/docs/introduction/supported-protocols.md b/docs/introduction/supported-protocols.md index a38366d..6376692 100644 --- a/docs/introduction/supported-protocols.md +++ b/docs/introduction/supported-protocols.md @@ -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