docs: Springwolf 1.0.0 release

Author: timonback

.github/styles/Vocab/Springwolf/accept.txt

@@ -4,10 +4,12 @@ Vocab = Springwolf
 MinAlertLevel = warning
 Packages = Microsoft
 
+[formats]
+mdx = md
 
 [*.md]
 BasedOnStyles = Vale, Microsoft
 
 BlockIgnores = (import .*;)
 
-Microsoft.Headings = NO
+Microsoft.Headings = NO

.vale.ini

@@ -36,4 +36,4 @@ vale sync
 vale docs/
 ```
 
-Words not part of the dictionary yet are added in [accept.txt](.github/styles/Vocab/Springwolf/accept.txt).
+Words not part of the dictionary yet are added in [accept.txt](.github/styles/config/vocabularies/Springwolf/accept.txt).

README.md

@@ -8,9 +8,9 @@ The following paragraphs describe how Springwolf works internally.
 
 ## Big Picture
 When the Spring Boot application is started, Springwolf uses its scanners to find defined consumers and producers within the application.
-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).
+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).
 
-The AsyncApi document is accessible an endpoint.
+The AsyncAPI document is accessible an endpoint.
 When the Springwolf UI is opened, the browser fetches the document and renders it (see demo).
 
 When publishing is enabled, the user can publish a message through the UI to another endpoint.
@@ -27,15 +27,15 @@ When building own scanner plugins, your plugin will need to implement the `Chann
 When the same channel/topic is found multiple times, it's merged as well.
 
 The result is a [`ChannelItem`](https://www.asyncapi.com/docs/reference/specification/v2.6.0#channelItemObject).
-The `ChannelItem` contains the `Message` for the subscribe and/or publish operation.
+The `ChannelObject` contains the `Message` for the receive and/or send operation.
 
 ## Building an example payload
 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.
+The payload is registered in the `ComponentsService`, which allows to split the `Message` from the schema definition - within the AsyncAPI doc a `$ref` references is used.
 
-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.
+Using `swagger-core` any class can be converted into an OpenApi schema.
+The schema is [mapped into an AsyncAPI schema](https://www.asyncapi.com/docs/tutorials/getting-started/coming-from-openapi) and included in the AsyncAPI document.
+Additionally, Springwolf generates an example 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.
 

docs/behind-the-scenes.md

@@ -40,4 +40,4 @@ public class AsyncApiTitleCustomizer implements AsyncApiCustomizer {
 
 All `ChannelScanner` beans are called to scan for channels.
 This interface is helpful when a protocol currently unsupported by Springwolf is used.
-Remember to register all payloads in the `SchemasService`.
+Remember to register all payloads in the `ComponentsService`.

docs/configuration/configuration.mdx

@@ -9,7 +9,7 @@ Add at least one binding so that readers know the protocol in use and functional
 
 To use the protocol specific bindings, ensure that you have added the corresponding [plugin](../introduction/supported-protocols.md).
 
-## Option 1: Annotations
+## Protocol specific annotations
 
 ### `@AmqpAsyncOperationBinding`
 
@@ -52,9 +52,12 @@ Associate this operation with SQS, see [operation-binding] for details.
 @SqsAsyncOperationBinding
 ```
 
-### `@AsyncGenericOperationBinding`
+## Generic annotation
 
 This binding is generic, so that any properties can be specified.
+
+### `@AsyncGenericOperationBinding`
+
 You can define anything and there is no validation.
 
 ```java
@@ -67,31 +70,6 @@ You can define anything and there is no validation.
 )
 ```
 
-## Option 2: AsyncApiDocket (deprecated)
-
-### `AmqpProducerData` / `AmqpConsumerData`
-
-```java
-    AmqpProducerData exampleProducer = AmqpProducerData.amqpProducerDataBuilder()
-        .queueName("example-producer-channel")
-        .description("example-producer-channel-description")
-        .exchangeName("example-topic-exchange")
-        .routingKey("example-topic-routing-key")
-        .payloadType(AnotherPayloadDto.class)
-        .build();
-```
-
-### `KafkaProducerData` / `KafkaConsumeData`
-
-```java
-    KafkaProducerData exampleProducerData = KafkaProducerData.kafkaProducerDataBuilder()
-        .topicName("example-producer-topic")
-        .description("Optional. Customer uploaded an example payload")
-        .payloadType(ExamplePayloadDto.class)
-        .headers(AsyncHeaders.NOT_USED)
-        .build();
-```
-
 ## Binding properties
 Explanation of the different binding properties.
 

docs/configuration/customizing.md

@@ -11,32 +11,31 @@ For these use-cases, Springwolf provides additional ways to explicitly add them
 
 To document consumers, either:
 - add the `@AsyncListener` annotation or
-- (deprecated) declare the `ConsumerData` object as part of the `AsyncApiDocket` or
 - rely on the auto-detection of `@JmsListener`, `@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.
+You are free to use both options together. Channel and operation, documented via `@AsyncListener` have a higher precedence than auto-detected annotations.
 
-## Option 1: `@AsyncListener`
+## `@AsyncListener`
 
 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`, `@KafkaAsyncOperationBinding` or `@AsyncGenericOperationBinding`, which has to be on the same method.
+On the same method, the protocol binding is defined. More details can be found in the [bindings](documenting-bindings.md) section.
 
 Below is an example to demonstrate the annotation:
 ```java
 @KafkaListener
 @AsyncListener(operation = @AsyncOperation(
         channelName = "example-consumer-topic",
-        description = "Optional. Customer uploaded an example payload",
-        servers = {"kafka"},
-        headers = @AsyncOperation.Headers(
+        description = "Customer uploaded an example payload", // Optional
+        servers = {"kafka"}, // Optional
+        headers = @AsyncOperation.Headers( // Optional
                 schemaName = "SpringKafkaDefaultHeaders",
                 values = {
                         @AsyncOperation.Headers.Header(
                                 name = DEFAULT_CLASSID_FIELD_NAME,
                                 description = "Spring Type Id Header",
-                                value = "io.github.stavshamir.springwolf.example.dtos.ExamplePayloadDto"
+                                value = "io.github.springwolf.example.dtos.ExamplePayloadDto"
                         ),
                         // (demonstrating https://cloudevents.io) 
                         @AsyncOperation.Headers.Header(
@@ -74,92 +73,7 @@ Optional. The headers describing the metadata of the payload.
 Optional. Useful when an application is connect to multiple brokers and wants to indicate to which broker the channel belongs to.
 The server needs to exist in [configuration > Servers](configuration.mdx) as well.
 
-
-## Option 2: `ConsumerData` (deprecated)
-
-:::note
-Must use configuration via `AsyncApiDocket` and can't use `application.properties`.
-:::
-
-Below is an example of describing a Kafka consumer:
-
-```java
-@Bean
-public AsyncApiDocket asyncApiDocket() {
-
-    ConsumerData exampleConsumerData = ConsumerData.builder()
-            .channelName("example-consumer-topic")
-            .description("Optional. Customer uploaded an example payload")
-            .operationBinding(ImmutableMap.of("kafka", new KafkaOperationBinding()))
-            .payloadType(ExamplePayloadDto.class)
-            .headers(AsyncHeaders.NOT_USED)
-            .build();
-  
-    return AsyncApiDocket.builder()
-            .basePackage(...)
-            .info(...)
-            .server(...)
-            .consumer(exampleConsumerData)
-            .build();
-}
-```
-
-Multiple consumers can be configured by calling the `consumer()` method multiple times.
-
-:::tip
-Use specific ConsumerData types `AmqpConsumerData` & `KafkaConsumerData` for protocol specific attributes
-:::
-
-### Channel Name
-
-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.
-
-### Description
-
-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.
-
-### Binding
-
-This property is used to discriminate the producer's protocol and provide protocol-specific properties (see [documenting bindings](documenting-bindings.md)).
-
-### Payload Type
-
-The class object of the payload that will be consumed from this channel.
-
-### Header
-
-Optional. The headers describing the metadata of the payload.
-By default, `AsyncHeaders.NOT_DOCUMENTED` is used to indicate that no explicit header documentation exists.
-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.
-
-
-### `AmqpConsumerData`
-
-The above Kafka `ConsumerData` equivalent in `AmqpConsumerData`:
-```java
-    AmqpConsumerData exampleConsumer = AmqpConsumerData.amqpConsumerDataBuilder()
-        .queueName("example-consumer-channel")
-        .description("example-consumer-channel-description")
-        .exchangeName("example-topic-exchange")
-        .routingKey("example-topic-routing-key")
-        .payloadType(AnotherPayloadDto.class)
-        .build();
-```
-
-### `KafkaConsumerData`
-
-The above Kafka `ConsumerData` simplifies to the following `KafkaConsumerData`:
-```java
-    KafkaConsumerData exampleConsumerData = KafkaConsumerData.kafkaConsumerDataBuilder()
-        .topicName("example-consumer-topic")
-        .description("Optional. Customer uploaded an example payload")
-        .payloadType(ExamplePayloadDto.class)
-        .headers(AsyncHeaders.NOT_USED)
-        .build();
-```
-
-
-## Option 3: `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener`
+## `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener`
 The `@JmsListener`, `@KafkaListener`, `@RabbitListener`, `@SqsListener` annotations are detected automatically.
 There is nothing more to do.
-Use the other options if the provided documentation is insufficient.
+Use the other option if the provided documentation is insufficient.

docs/configuration/documenting-bindings.md

@@ -10,7 +10,7 @@ import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml';
 
 # Messages
 
-Springwolf provides different ways to document the messages. The `message` is part of the AsyncApi `operationObject`
+Springwolf provides different ways to document the messages. The `message` is part of the AsyncAPI `operationObject`
 
 > A definition of the message that will be published or received by this operation
 
@@ -20,25 +20,25 @@ For example:
 ```java
 @AsyncPublisher(operation = @AsyncOperation(
         channelName = "example-producer-topic",
-        description = "Optional. Customer uploaded an example payload",
-        payloadType = ExamplePayloadDto.class, // optional
-        message = @AsyncMessage(
+        description = "Customer uploaded an example payload", // Optional
+        payloadType = ExamplePayloadDto.class, // Optional
+        message = @AsyncMessage( // Optional
                 messageId = "my-unique-id",
                 name = "ExamplePayloadDto",
-                schemaFormat = "application/schema+json;version=draft-07",
+                schemaFormat = "application/vnd.aai.asyncapi+json;version=3.0.0",
                 description = "Example payload model for sending messages"
         )
 ))
 public void sendMessage(ExamplePayloadDto msg) {
-    // send
+    // process
 }
 ```
 
 ## Payload Type
 
 Springwolf tries to auto-detect the payload type based on the method signature.
 
-When the method has multiple arguments, the payload can be indicated via `@Payload`, i.e.
+When the method has multiple arguments, the payload can be indicated via `@Payload`, that's
 ```java
 public void sendMessage(@Payload ExamplePayloadDto msg, String traceId, Object loggingContext) {}
 ```
@@ -74,7 +74,7 @@ The default Jackson `ModelResolver` supports schema definitions via `@Schema` to
 
 The `@Schema` annotation allows to set many properties like `description`, `example`, `requiredMode`, `minimum` to document payloads.
 
-All properties are part of the produced AsyncApi file. However, not all are displayed in `springwolf-ui` (see [#378](https://github.com/springwolf/springwolf-core/issues/378))
+All properties are part of the produced AsyncAPI file. However, not all are displayed in `springwolf-ui` (see [#378](https://github.com/springwolf/springwolf-core/issues/378))
 
 #### Usage
 
@@ -112,11 +112,11 @@ public class ExamplePayloadDto {
 The `@AsyncMessage.description` field will always override the `@Schema` description if provided
 :::
 
-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)
+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/springwolf/examples/amqp/dtos/ExamplePayloadDto.java)
 
 #### Primitive, final and external classes
 
-When the `@Schema` annotation cannot be attached to the payload class (i.e. `java.lang.String`), the payload can be wrapped in an envelope class. The actual payload is a field within this class (`StringEnvelope`), marked using `@AsyncApiPayload` and documented using the `@Schema` annotation.
+When the `@Schema` annotation can't be attached to the payload class (that's `java.lang.String`), the payload can be wrapped in an envelope class. The actual payload is a field within this class (`StringEnvelope`), marked using `@AsyncApiPayload` and documented using the `@Schema` annotation.
 
 ```java
 @AsyncListener( operation = @AsyncOperation( channelName = TOPIC,
@@ -136,7 +136,7 @@ static class StringEnvelope {
 
 ### `json-schema`
 
-The [`springwolf-add-ons/springwolf-json-schema`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-json-schema) adds the [json-schema](https://json-schema.org) schema to the AsyncApi document. 
+The [`springwolf-add-ons/springwolf-json-schema`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-json-schema) adds the [json-schema](https://json-schema.org) schema to the AsyncAPI document.
 
 ## Custom ModelConverters