### Run Springwolf Example with Docker Compose

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-cloud-stream-example/README.md

Use this command to start the Springwolf example application and its dependencies using Docker Compose. This is the recommended method for running the example.

```bash
docker-compose up
```

--------------------------------

### Install Playwright Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/e2e/README.md

Run this command to install the necessary dependencies for Playwright testing.

```bash
npm install
```

--------------------------------

### Specify Example Project for Testing

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/e2e/README.md

Set the SPRINGWOLF_EXAMPLE environment variable to test against a non-default example project. Note that switching projects may require stopping existing Docker containers.

```bash
SPRINGWOLF_EXAMPLE=kafka npm run start
```

--------------------------------

### Run Springwolf Example with Gradle

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-cloud-stream-example/README.md

Instructions for running the Springwolf Cloud Stream example using Gradle. Ensure you clone the repository and navigate to the example directory before executing these commands. Note that the IntelliJ spring application might not include springwolf-ui correctly, so using `bootRun` is advised.

```bash
git clone https://github.com/springwolf/springwolf-core.git
```

```bash
cd springwolf-core/springwolf-examples/springwolf-cloud-stream-example
```

```bash
docker compose up kafka -d
```

```bash
../../gradlew bootRun
```

--------------------------------

### Start Playwright UI

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/e2e/README.md

Execute this command to launch the Playwright UI for interactive testing.

```bash
npm run start
```

--------------------------------

### Example JSON Schema Output

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-add-ons/springwolf-json-schema/README.md

This is an example of the JSON schema generated by the add-on, showing the 'x-json-schema' field added to a schema definition.

```json
{
  "MonetaryAmount-Header": {
    "...": "",
    "x-json-schema": {
      "$schema": "https://json-schema.org/draft-07/schema#",
      "name": "MonetaryAmount-Header",
      "properties": {
        "__TypeId__": {
          "description": "Spring Type Id Header",
          "enum": [
            "javax.money.MonetaryAmount"
          ],
          "type": "string"
        }
      },
      "type": "object"
    }
  }
}

```

--------------------------------

### Access Springwolf UI and Docs via Curl (Gradle)

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-cloud-stream-example/README.md

After starting the application with Gradle, use these commands to access the Springwolf AsyncAPI UI and documentation API. This allows you to visualize your AsyncAPI schema and test message publishing.

```bash
curl http://localhost:8080/springwolf/docs
```

--------------------------------

### Access Springwolf UI and Docs via Curl

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-cloud-stream-example/README.md

After starting the application, use these commands to access the Springwolf AsyncAPI UI and documentation API. This allows you to visualize your AsyncAPI schema and test message publishing.

```bash
curl localhost:8080/springwolf/docs
```

--------------------------------

### Documenting an AMQP Message Producer with @AsyncPublisher

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use @AsyncPublisher to register a publish operation for message producers. It documents the channel, description, headers, and message details. This example uses AMQP binding annotations for RabbitMQ-specific configurations like delivery mode.

```java
import io.github.springwolf.core.asyncapi.annotations.*;
import io.github.springwolf.bindings.amqp.annotations.AmqpAsyncOperationBinding;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.stereotype.Component;

@Component
public class NotificationProducer {

    private final RabbitTemplate rabbitTemplate;

    public NotificationProducer(RabbitTemplate rabbitTemplate) {
        this.rabbitTemplate = rabbitTemplate;
    }

    @AsyncPublisher(operation = @AsyncOperation(
            channelName = "notifications-exchange",
            description = "Publishes notification events to subscribers.",
            headers = @AsyncOperation.Headers(
                    values = {
                        @AsyncOperation.Headers.Header(
                                name = "x-correlation-id",
                                description = "Correlation ID for tracing",
                                type = io.github.springwolf.asyncapi.v3.model.schema.SchemaType.STRING,
                                format = "uuid")
                    }
            )))
    @AmqpAsyncOperationBinding(deliveryMode = 2, mandatory = true)
    public void sendNotification(NotificationPayload payload) {
        rabbitTemplate.convertAndSend("notifications-exchange", "notification.created", payload);
    }
}
```

--------------------------------

### Generic Protocol Binding with @AsyncGenericOperationBinding

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Utilize @AsyncGenericOperationBinding from the springwolf-generic-binding add-on to document operation bindings for unsupported protocols. This example configures a custom protocol with specific fields.

```java
import io.github.springwolf.addons.generic_binding.annotation.AsyncGenericOperationBinding;
import io.github.springwolf.core.asyncapi.annotations.*;
import org.springframework.stereotype.Component;

@Component
public class CustomProtocolConsumer {

    @AsyncListener(operation = @AsyncOperation(
            channelName = "custom-channel",
            description = "Consumes messages from a custom broker"))
    @AsyncGenericOperationBinding(
            type = "my-custom-protocol",
            fields = {
                "bindingVersion=1.0",
                "qos=at-least-once",
                "retryCount=3"
            })
    public void receiveMessage(CustomPayload payload) {
        // handle message
    }
}
```

--------------------------------

### AMQP Operation Binding with @AmqpAsyncOperationBinding

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use @AmqpAsyncOperationBinding to attach AMQP-specific metadata to @AsyncListener or @AsyncPublisher. This example shows publishing an invoice event with delivery mode and mandatory flags set.

```java
import io.github.springwolf.bindings.amqp.annotations.AmqpAsyncOperationBinding;
import io.github.springwolf.core.asyncapi.annotations.*;
import org.springframework.amqp.rabbit.annotation.RabbitListener;
import org.springframework.amqp.rabbit.core.RabbitTemplate;
import org.springframework.stereotype.Component;

@Component
public class InvoiceService {

    private final RabbitTemplate rabbitTemplate;

    public InvoiceService(RabbitTemplate rabbitTemplate) {
        this.rabbitTemplate = rabbitTemplate;
    }

    // Producer: document with @AsyncPublisher
    @AsyncPublisher(operation = @AsyncOperation(
            channelName = "invoice-exchange",
            description = "Publishes invoice ready events"))
    @AmqpAsyncOperationBinding(deliveryMode = 2, mandatory = true, ack = true)
    public void publishInvoice(InvoicePayload invoice) {
        rabbitTemplate.convertAndSend("invoice-exchange", "invoice.ready", invoice);
    }

    // Consumer: auto-detected from @RabbitListener, no extra annotation needed
    @RabbitListener(queues = "invoice-queue")
    public void processInvoice(InvoicePayload invoice) {
        // handle invoice
    }
}
```

--------------------------------

### Development Commands

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-ui/README.md

Commands for managing dependencies, running the development server, testing, and updating the project during development.

```bash
npm i
../gradlew npmInstall
```

```bash
npm start
../gradlew npmStart
```

```bash
npm run test
../gradlew pnpm_run_test
```

```bash
npm run update
../gradlew pnpm_run_update
```

--------------------------------

### Retrieve UI Configuration

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetch the UI configuration, including group names and default display settings for the Springwolf UI.

```bash
curl -s http://localhost:8080/springwolf/ui-config | jq .
```

--------------------------------

### Configure Springwolf Stomp Plugin

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-stomp-plugin/README.md

Set up application.properties to configure the base package for scanning and server details for Stomp.

```properties
springwolf.docket.base-package=io.github.springwolf.examples

springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0

springwolf.docket.servers.stomp.protocol=stomp
springwolf.docket.servers.stomp.host=localhost:8080
```

--------------------------------

### Upload GPG Key to Keyserver

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Upload your public GPG key to the Ubuntu keyserver. Replace '5A86573F7588809B50EB8EF475ABBF11907B8027' with your actual key ID.

```bash
gpg --keyserver keyserver.ubuntu.com --send-keys 5A86573F7588809B50EB8EF475ABBF11907B8027
```

--------------------------------

### Retrieve AsyncAPI Document (YAML)

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetch the AsyncAPI v3 document in YAML format by setting the `Accept` header.

```bash
curl -s -H "Accept: application/yaml" http://localhost:8080/springwolf/docs
```

--------------------------------

### Configure SNAPSHOT Repository and Dependency

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Add the Sonatype snapshot repository and the Springwolf Kafka dependency to your build.gradle file.

```groovy
// build.gradle
repositories {
    maven {
        url "https://central.sonatype.com/repository/maven-snapshots/"
    }
}

dependencies {
    implementation "io.github.springwolf:springwolf-kafka:2.4.0-SNAPSHOT"
}
```

--------------------------------

### Configure Kafka Publishing

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Enable and configure the Kafka producer for message publishing. Ensure bootstrap servers and serializers are correctly set.

```properties
springwolf.plugin.kafka.publishing.enabled=true
sspringwolf.plugin.kafka.publishing.producer.bootstrap-servers=localhost:9093
sspringwolf.plugin.kafka.publishing.producer.key-serializer=org.apache.kafka.common.serialization.StringSerializer
sspringwolf.plugin.kafka.publishing.producer.value-serializer=org.springframework.kafka.support.serializer.JacksonJsonSerializer
```

--------------------------------

### Enable AMQP Publishing

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Enable message publishing for the AMQP plugin.

```properties
springwolf.plugin.amqp.publishing.enabled=true
```

--------------------------------

### Generate New GPG Key

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Command to generate a new GPG key. Follow the prompts to set up your key.

```bash
gpg --full-generate-key
```

--------------------------------

### STOMP Client Connection and Subscription

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-stomp-example/src/main/resources/static/index.html

Establishes a STOMP connection, subscribes to various queues, and handles incoming messages. Activate the client to initiate the connection.

```javascript
import { Client } from '@stomp/stompjs';
var stompClient = null;
stompClient = new Client({
    brokerURL: 'ws://localhost:8080/myendpoint',
    onConnect: (frame) => {
        console.log('Connected: ' + JSON.stringify(frame));
        document.getElementById('username').innerText = frame.headers['user-name'];
        stompClient.subscribe('/queue/another-queue', function(messageOutput) {
            const data = JSON.parse(messageOutput.body);
            showMessageOutput(data);
        });
        stompClient.subscribe('/topic/sendto-response-queue', function(messageOutput) {
            const data = JSON.parse(messageOutput.body);
            showSendToMessageOutput(data);
        });
        stompClient.subscribe('/user/queue/sendtouser-response-queue', function(messageOutput) {
            const data = JSON.parse(messageOutput.body);
            showSendToUserMessageOutput(data);
        });
        sendMessage();
    },
});
stompClient.activate();
```

--------------------------------

### Search GPG Key

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Use this command to search for the Springwolf GPG key on the Ubuntu keyserver.

```bash
gpg --keyserver keyserver.ubuntu.com --search-keys 5A86573F7588809B50EB8EF475ABBF11907B8027
```

--------------------------------

### Configure Springwolf AMQP Plugin Properties

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-amqp-plugin/README.md

Set these properties in `application.properties` to configure the Springwolf docket, including the base package for scanning and server details.

```properties
springwolf.docket.base-package=io.github.springwolf.examples

springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0

springwolf.docket.servers.amqp.protocol=amqp
springwolf.docket.servers.amqp.host=amqp:5672
```

--------------------------------

### Retrieve UI configuration

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetches the configuration for the Springwolf UI, including initial display settings and available groups.

```APIDOC
## GET /springwolf/ui-config — Retrieve UI configuration

### Description
Returns UI configuration (group names and default display settings).

### Method
GET

### Endpoint
/springwolf/ui-config

### Request Example
```bash
curl -s http://localhost:8080/springwolf/ui-config | jq .
```

### Response Example
```json
{
  "initialConfig": {
    "showBindings": true,
    "showHeaders": true
  },
  "groups": [
    { "name": "OrdersOnly" }
  ]
}
```
```

--------------------------------

### Configure AsyncApiDocket Programmatically

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use AsyncApiDocket.builder() to programmatically configure the AsyncAPI docket as an alternative to application.properties. This bean defines the base package, ID, API information, servers, and default content type.

```java
import io.github.springwolf.asyncapi.v3.model.info.Contact;
import io.github.springwolf.asyncapi.v3.model.info.Info;
import io.github.springwolf.asyncapi.v3.model.info.License;
import io.github.springwolf.asyncapi.v3.model.server.Server;
import io.github.springwolf.core.configuration.docket.AsyncApiDocket;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.Map;

@Configuration
public class AsyncApiConfig {

    @Bean
    public AsyncApiDocket asyncApiDocket() {
        return AsyncApiDocket.builder()
                .basePackage("com.example.myapp")
                .id("urn:com:example:myapp")
                .info(Info.builder()
                        .title("Order Processing Service")
                        .version("3.0.0")
                        .description("Handles order lifecycle events via Kafka and RabbitMQ.")
                        .contact(Contact.builder()
                                .name("Platform Engineering")
                                .email("platform@example.com")
                                .url("https://wiki.example.com/platform")
                                .build())
                        .license(License.builder()
                                .name("Apache License 2.0")
                                .url("https://www.apache.org/licenses/LICENSE-2.0")
                                .build())
                        .build())
                .servers(Map.of(
                        "kafka-prod", Server.builder()
                                .host("kafka.example.com:9092")
                                .protocol("kafka")
                                .build(),
                        "rabbitmq-prod", Server.builder()
                                .host("rabbitmq.example.com:5672")
                                .protocol("amqp")
                                .build()))
                .defaultContentType("application/json")
                .build();
    }
}
```

--------------------------------

### Publish Test Message to AMQP

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Publish a test message to an AMQP exchange.

```bash
curl -s -X POST \
  "http://localhost:8080/springwolf/plugin/amqp/publish?topic=invoice-exchange" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": {},
    "headers": {},
    "payload": "{\"invoiceId\": \"INV-2024-001\", \"total\": 450.00}" 
  }'
```

--------------------------------

### Retrieve AsyncAPI Document (JSON)

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetch the complete AsyncAPI v3 document in JSON format. Use `jq` for pretty-printing and filtering.

```bash
curl -s http://localhost:8080/springwolf/docs | jq .
```

--------------------------------

### Run Playwright Tests with Gradle Wrapper

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/e2e/README.md

Alternatively, use the Gradle wrapper to execute Playwright tests.

```bash
../../gradlew pnpm_run_test
```

--------------------------------

### Apply Code Formatting

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-ui/README.md

Use this command to check and automatically fix code formatting violations using Spotless.

```bash
../gradlew spotlessApply
```

--------------------------------

### Build AsyncAPI Specification

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-asyncapi/README.md

Use the AsyncAPI builder to construct an AsyncAPI specification object with info, channels, and operations.

```java
AsyncAPI asyncAPI = AsyncAPI.builder()
        .info(Info.builder()
                .title("Account Service")
                .version("1.0.0")
                .description("This service is in charge of processing user signups")
                .build())
        .channels(Map.of(
                "userSignedup",
                Channel.builder().build()))
        .operations(Map.of(
                "sendUserSignedup",
                Operation.builder().build()))
        .build();
```

--------------------------------

### Retrieve AsyncAPI document (YAML)

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetches the AsyncAPI v3 document in YAML format. This is an alternative format for viewing the event-driven architecture documentation.

```APIDOC
## GET /springwolf/docs (YAML) — Retrieve AsyncAPI document as YAML

### Description
Returns the AsyncAPI v3 document as YAML.

### Method
GET

### Endpoint
/springwolf/docs

### Request Example
```bash
curl -s -H "Accept: application/yaml" http://localhost:8080/springwolf/docs
```

### Response Example
```yaml
asyncapi: 3.0.0
info:
  title: My Event-Driven App
  version: 2.1.0
channels:
  orders:
    address: orders
    messages: ...
```
```

--------------------------------

### Add Springwolf AMQP Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-amqp-plugin/README.md

Include these dependencies in your build file to enable the Springwolf AMQP plugin and its UI.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-amqp:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Springwolf Core Configuration Properties

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Configure Springwolf behavior using application.properties or application.yml. This snippet shows common settings like enabling Springwolf, setting init mode, and defining base packages.

```properties
# Enable/disable Springwolf entirely
springwolf.enabled=true

# Init mode: FAIL_FAST (default) or BACKGROUND
springwolf.init-mode=FAIL_FAST

# Use fully qualified class names in schemas (e.g., java.lang.String vs String)
springwolf.use-fqn=true

# AsyncAPI Studio compatibility mode
springwolf.studio-compatibility=true

# Base path for all Springwolf endpoints (default: /springwolf)
springwolf.path.base=/springwolf
springwolf.path.docs=/docs

# Base package to scan for listeners/publishers
springwolf.docket.base-package=com.example.myapp

# Application metadata (AsyncAPI info object)
springwolf.docket.info.title=My Event-Driven App
springwolf.docket.info.version=2.1.0
springwolf.docket.info.description=AsyncAPI documentation for the order processing service.
springwolf.docket.info.terms-of-service=https://example.com/terms
springwolf.docket.info.contact.name=Platform Team
springwolf.docket.info.contact.email=platform@example.com
springwolf.docket.info.contact.url=https://example.com
springwolf.docket.info.license.name=Apache License 2.0
springwolf.docket.info.extension-fields.x-api-audience=company-internal

# Server definitions
springwolf.docket.servers.kafka-server.protocol=kafka
springwolf.docket.servers.kafka-server.host=localhost:9092

springwolf.docket.servers.amqp-server.protocol=amqp
springwolf.docket.servers.amqp-server.host=localhost:5672

# Default content type
springwolf.docket.default-content-type=application/json

# Group filtering (creates scoped AsyncAPI views)
springwolf.docket.group-configs[0].group=OrdersOnly
springwolf.docket.group-configs[0].info.description=Only order-related channels
springwolf.docket.group-configs[0].channel-name-to-match=.*order.*
springwolf.docket.group-configs[0].message-name-to-match=.*Order.*
springwolf.docket.group-configs[0].action-to-match=RECEIVE

# UI defaults
springwolf.ui.defaults.show-bindings=true
springwolf.ui.defaults.show-headers=true

# Enable/disable scanner components
springwolf.scanner.async-listener.enabled=true
springwolf.scanner.async-publisher.enabled=true

# Payload unwrapping (extractable generic wrapper classes)
springwolf.payload.extractable-classes.org.apache.kafka.clients.consumer.ConsumerRecord=1

```

--------------------------------

### Configure Springwolf Kafka Plugin Properties

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-kafka-plugin/README.md

Set these properties in your application.properties file to configure the Springwolf Kafka plugin. Ensure 'springwolf.docket.base-package' points to your Kafka listener classes.

```properties
springwolf.docket.base-package=io.github.springwolf.examples

springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0

springwolf.docket.servers.kafka.protocol=kafka
springwolf.docket.servers.kafka.host=${kafka.bootstrap.servers:localhost:29092}
```

--------------------------------

### Add Sonatype Snapshots Repository to build.gradle

Source: https://github.com/springwolf/springwolf-core/blob/main/README.md

Configure your build.gradle file to include the Sonatype snapshots repository for accessing snapshot versions.

```groovy
repositories {
    // ...
    maven {
        url "https://central.sonatype.com/repository/maven-snapshots/" // build.gradle
        // url = uri("https://central.sonatype.com/repository/maven-snapshots/") // build.gradle.kts
    }
}
```

--------------------------------

### Add Springwolf AsyncAPI Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-asyncapi/README.md

Include this dependency to enable the JVM Builders for creating an AsyncAPI Spec file.

```groovy
dependencies {
    // Provides the JVM Builders to create an AsyncAPI Spec file    
    implementation 'io.github.springwolf:springwolf-asyncapi:<springwolf-version>'
}
```

--------------------------------

### Add Springwolf SQS Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-sqs-plugin/README.md

Include these dependencies in your build file to enable the Springwolf SQS plugin and its UI.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-sqs:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Add Springwolf UI Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-ui/README.md

Add this dependency to your project to include the Springwolf UI. Replace `<springwolf-version>` with the desired version.

```groovy
dependencies {
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Publish Test Message to Kafka

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Publish a test message to a Kafka topic. Requires `springwolf.plugin.kafka.publishing.enabled=true`. The response indicates success (200 OK), failure (404), or bad request (400) if payload deserialization fails.

```bash
curl -s -X POST \
  "http://localhost:8080/springwolf/plugin/kafka/publish?topic=orders" \
  -H "Content-Type: application/json" \
  -d '{
    "bindings": {
      "key": "order-key-001"
    },
    "headers": {
      "__TypeId__": "com.example.OrderPayload"
    },
    "payload": "{\"orderId\": \"ORD-001\", \"amount\": 99.99, \"status\": \"NEW\"}"
  }'
```

--------------------------------

### Export GPG Private Key

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Export your private GPG key in armored format for backup. Replace '75ABBF11907B8027' with your actual key ID.

```bash
gpg --armor --export-secret-key 75ABBF11907B8027 > springwolf.gpg.key
```

--------------------------------

### Configure Kafka Channel Binding with @KafkaAsyncChannelBinding

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Define Kafka topic configurations such as partitions, replicas, retention policies, and cleanup policies using @KafkaAsyncChannelBinding. This annotation attaches topic-specific settings to a method annotation.

```java
import io.github.springwolf.bindings.kafka.annotations.*;
import io.github.springwolf.core.asyncapi.annotations.*;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class EventLogConsumer {

    @KafkaListener(topics = "event-log")
    @AsyncListener(operation = @AsyncOperation(channelName = "event-log"))
    @KafkaAsyncChannelBinding(
            topic = "event-log",
            partitions = 6,
            replicas = 3,
            topicConfiguration = @KafkaAsyncChannelBinding.KafkaChannelTopicConfiguration(
                    cleanup = {KafkaAsyncChannelBinding.KafkaChannelTopicConfiguration.CleanupPolicy.DELETE},
                    retentionMs = 604800000L,   // 7 days
                    retentionBytes = -1L,
                    maxMessageBytes = 1048576))
    @KafkaAsyncOperationBinding
    public void consumeEvent(EventPayload payload) {
        // consume
    }
```

--------------------------------

### Add Springwolf Stomp Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-stomp-plugin/README.md

Include these dependencies in your build file to enable the Springwolf Stomp plugin and its optional UI.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-stomp:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Add Springwolf Kafka Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-kafka-plugin/README.md

Include these dependencies in your project to enable the Springwolf Kafka plugin. The UI dependency is optional but recommended for easy access to documentation.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-kafka:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Define AsyncAPI Document Groups Programmatically

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Configure AsyncApiGroup beans to split the AsyncAPI document into different views based on operation actions, channel name patterns, or message name patterns. This allows for scoped API documentation.

```java
import io.github.springwolf.asyncapi.v3.model.operation.OperationAction;
import io.github.springwolf.core.configuration.docket.AsyncApiGroup;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.List;
import java.util.regex.Pattern;

@Configuration
public class AsyncApiGroupConfig {

    @Bean
    public AsyncApiGroup consumersGroup() {
        return AsyncApiGroup.builder()
                .groupName("consumers")
                .operationActionsToKeep(List.of(OperationAction.RECEIVE))
                .build();
    }

    @Bean
    public AsyncApiGroup vehicleEventsGroup() {
        return AsyncApiGroup.builder()
                .groupName("vehicle-events")
                .channelNamesToKeep(List.of(Pattern.compile(".*vehicle.* செறிவு")))
                .messageNamesToKeep(List.of(Pattern.compile(".*Vehicle.* செறிவு")))
                .build();
    }
}
```

--------------------------------

### Export GPG Public Key

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Export your public GPG key in armored format. Replace '75ABBF11907B8027' with your actual key ID.

```bash
gpg --armor --export 75ABBF11907B8027 > springwolf.gpg.pub
```

--------------------------------

### Publish a test message to AMQP

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Triggers the publishing of a test message directly to an AMQP exchange. This is useful for testing message production to AMQP-compatible message brokers.

```APIDOC
## POST /springwolf/plugin/amqp/publish — Publish a test message to AMQP

### Description
Triggers message publishing directly from the UI or via REST.

### Method
POST

### Endpoint
/springwolf/plugin/amqp/publish

### Parameters
#### Query Parameters
- **topic** (string) - Required - The AMQP exchange to publish the message to.

#### Request Body
- **bindings** (object) - Optional - AMQP-specific bindings.
- **headers** (object) - Optional - Message headers.
- **payload** (string) - Required - The message payload, typically a JSON string.

### Request Example
```bash
curl -s -X POST \
  "http://localhost:8080/springwolf/plugin/amqp/publish?topic=invoice-exchange" \
  -H "Content-Type: application/json" \
  -d 
    "{
    \"bindings\": {},
    \"headers\": {},
    \"payload\": \"{\"invoiceId\": \"INV-2024-001\", \"total\": 450.00}\"\n  }"
```
```

--------------------------------

### Display Schema Range Constraints

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-ui/src/app/components/schema/range/range.component.html

Renders the appropriate string representation for schema range constraints based on lower and upper bounds, and their inclusivity. Use this when displaying schema details that include range specifications.

```HTML
@if (lowerBound() != undefined && upperBound() == undefined) { {{ lowerBoundInclusive() ? ">=" : ">" }} {{ lowerBound() }} }
@if (lowerBound() == undefined && upperBound() != undefined) { {{ upperBoundInclusive() ? "<=" : "<" }} {{ upperBound() }} }
@if (lowerBound() != undefined && upperBound() != undefined) { {{ lowerBoundInclusive() ? "[" : "(" }} {{ lowerBound() }} .. {{ upperBound() }} {{ upperBoundInclusive() ? "]" : ")" }}
```

--------------------------------

### Run Playwright Tests via CLI

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/e2e/README.md

Use this command for running Playwright tests in CI/CD or CLI environments.

```bash
npm run test
```

--------------------------------

### Add Sonatype Snapshots Repository to pom.xml

Source: https://github.com/springwolf/springwolf-core/blob/main/README.md

Configure your pom.xml file to include the Sonatype snapshots repository for accessing snapshot versions when using Maven.

```xml
<repositories>
    <repository>
        <id>oss-sonatype</id>
        <name>oss-sonatype</name>
        <url>https://central.sonatype.com/repository/maven-snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>
```

--------------------------------

### Retrieve AsyncAPI document (JSON)

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Fetches the complete AsyncAPI v3 document in JSON format. This endpoint provides a comprehensive view of the event-driven architecture.

```APIDOC
## GET /springwolf/docs — Retrieve the AsyncAPI document (JSON)

### Description
Returns the full AsyncAPI v3 document as JSON.

### Method
GET

### Endpoint
/springwolf/docs

### Request Example
```bash
curl -s http://localhost:8080/springwolf/docs | jq .
```

### Response Example
```json
{
  "asyncapi": "3.0.0",
  "info": {
    "title": "My Event-Driven App",
    "version": "2.1.0",
    ...
  },
  "channels": { ... },
  "operations": { ... },
  "components": { ... }
}
```
```

--------------------------------

### Add Springwolf SNS Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-sns-plugin/README.md

Include these dependencies in your project to enable the Springwolf SNS plugin and its UI.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-sns:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Publish a test message to Kafka

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Triggers the publishing of a test message directly to a Kafka topic. This requires `springwolf.plugin.kafka.publishing.enabled=true` and is useful for testing message production.

```APIDOC
## POST /springwolf/plugin/kafka/publish — Publish a test message to Kafka

### Description
Triggers message publishing directly from the UI or via REST. Requires `springwolf.plugin.kafka.publishing.enabled=true`.

### Method
POST

### Endpoint
/springwolf/plugin/kafka/publish

### Parameters
#### Query Parameters
- **topic** (string) - Required - The Kafka topic to publish the message to.

#### Request Body
- **bindings** (object) - Optional - Kafka-specific bindings, e.g., message key.
  - **key** (string) - Optional - The message key.
- **headers** (object) - Optional - Message headers.
  - **__TypeId__** (string) - Optional - The type ID of the payload.
- **payload** (string) - Required - The message payload, typically a JSON string.

### Request Example
```bash
curl -s -X POST \
  "http://localhost:8080/springwolf/plugin/kafka/publish?topic=orders" \
  -H "Content-Type: application/json" \
  -d 
    "{
    \"bindings\": {\n      \"key\": \"order-key-001\"\n    },\n    \"headers\": {\n      \"__TypeId__\": \"com.example.OrderPayload\"\n    },\n    \"payload\": \"{\"orderId\": \"ORD-001\", \"amount\": 99.99, \"status\": \"NEW\"}\"\n  }"
```

### Response
#### Success Response (200 OK)
Indicates the message was successfully published.

#### Error Response (404 Not Found)
Returned if publishing is not enabled.

#### Error Response (400 Bad Request)
Returned if payload deserialization fails.
```

--------------------------------

### Retrieve Filtered AsyncAPI Document by Group

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Obtain a scoped AsyncAPI document for a specific group. This is useful for filtering channels based on `springwolf.docket.group-configs`.

```bash
curl -s http://localhost:8080/springwolf/docs/OrdersOnly | jq .info.description
```

```bash
curl -s http://localhost:8080/springwolf/docs/OrdersOnly | jq '.channels | keys'
```

--------------------------------

### List Secret GPG Keys

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Retrieve the key ID for your secret GPG keys. Use the LONG format for clarity.

```bash
gpg --list-secret-keys --keyid-format LONG
```

--------------------------------

### Add Springwolf JMS Plugin Dependencies

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-plugins/springwolf-jms-plugin/README.md

Include these dependencies in your build file to enable the Springwolf JMS plugin and its optional UI.

```groovy
dependencies {
    // Provides the documentation API    
    implementation 'io.github.springwolf:springwolf-jms:<springwolf-version>'

    // Provides the UI - optional (recommended)
    runtimeOnly 'io.github.springwolf:springwolf-ui:<springwolf-version>'
}
```

--------------------------------

### Add Springwolf Common Model Converters Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-add-ons/springwolf-common-model-converters/README.md

Add this dependency to include the common model converters in your project. Replace `<springwolf-version>` with the desired Springwolf version.

```groovy
dependencies {
    implementation 'io.github.springwolf:springwolf-common-model-converters:<springwolf-version>'
}
```

--------------------------------

### Generate GPG Revocation Certificate

Source: https://github.com/springwolf/springwolf-core/blob/main/RELEASING.md

Create a revocation certificate for your GPG key. Replace '5A86573F7588809B50EB8EF475ABBF11907B8027' with your actual key ID.

```bash
gpg --output springwolf.gpg.revoke.asc --gen-revoke 5A86573F7588809B50EB8EF475ABBF11907B8027
```

--------------------------------

### Customize AsyncAPI Document with AsyncApiCustomizer

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Implement the AsyncApiCustomizer interface and register it as a Spring bean to modify the final AsyncAPI object after Springwolf scanning. This can be used to inject global extension fields or remove internal channels.

```java
import io.github.springwolf.asyncapi.v3.model.AsyncAPI;
import io.github.springwolf.core.asyncapi.AsyncApiCustomizer;
import org.springframework.stereotype.Component;

import java.util.Map;

@Component
public class CompanyAsyncApiCustomizer implements AsyncApiCustomizer {

    @Override
    public void customize(AsyncAPI asyncAPI) {
        // Inject global extension fields
        if (asyncAPI.getInfo() != null) {
            asyncAPI.getInfo().setDescription(
                    asyncAPI.getInfo().getDescription() + "\n\n_Generated by Springwolf_");
        }

        // Remove internal channels from external-facing document
        if (asyncAPI.getChannels() != null) {
            asyncAPI.getChannels().entrySet().removeIf(entry ->
                    entry.getKey().startsWith("internal."));
        }
    }
}
```

--------------------------------

### Configure Kafka Operation Binding with @KafkaAsyncOperationBinding

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Attach Kafka-specific operation binding metadata like group ID, client ID, and message key to @AsyncListener or @AsyncPublisher annotations. The message key can be described and exemplified.

```java
import io.github.springwolf.bindings.kafka.annotations.*;
import io.github.springwolf.core.asyncapi.annotations.*;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class PaymentConsumer {

    @KafkaListener(topics = "payments")
    @AsyncListener(operation = @AsyncOperation(channelName = "payments"))
    @KafkaAsyncOperationBinding(
            groupId = "payment-processor-group",
            clientId = "payment-client-01",
            messageBinding = @KafkaAsyncOperationBinding.KafkaAsyncMessageBinding(
                    key = @KafkaAsyncOperationBinding.KafkaAsyncKey(
                            description = "Payment transaction ID",
                            example = "txn-00001")))
    public void processPayment(PaymentPayload payload) {
        // process payment
    }
```

--------------------------------

### Displaying Incoming Messages

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-examples/springwolf-stomp-example/src/main/resources/static/index.html

Helper functions to display messages received from the STOMP server in the browser's DOM. Each function targets a specific output area.

```javascript
function showMessageOutput(messageOutput) {
    console.log(messageOutput);
    document.getElementById('server-comm').innerHTML += '<p>' + JSON.stringify(messageOutput) + '</p>';
}
function showSendToMessageOutput(messageOutput) {
    console.log(messageOutput);
    document.getElementById('server-comm-sendTo').innerHTML += '<p>' + JSON.stringify(messageOutput) + '</p>';
}
function showSendToUserMessageOutput(messageOutput) {
    console.log(messageOutput);
    document.getElementById('server-comm-sendToUser').innerHTML += '<p>' + JSON.stringify(messageOutput) + '</p>';
}
```

--------------------------------

### Add Springwolf Json Schema Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-add-ons/springwolf-json-schema/README.md

Add this dependency to your project to enable JSON schema generation. It is a runtime dependency.

```groovy
dependencies {
    runtimeOnly 'io.github.springwolf:springwolf-json-schema:<springwolf-version>'
}
```

--------------------------------

### Customize Operations with OperationCustomizer

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Implement the OperationCustomizer interface to customize individual Operation objects after scanning. This is useful for adding tags, extensions, or making conditional modifications based on the method's class or package.

```java
import io.github.springwolf.asyncapi.v3.model.operation.Operation;
import io.github.springwolf.core.asyncapi.scanners.operations.OperationCustomizer;
import org.springframework.stereotype.Component;

import java.lang.reflect.Method;
import java.util.List;
import java.util.Map;

@Component
public class TaggingOperationCustomizer implements OperationCustomizer {

    @Override
    public void customize(Operation operation, Method method) {
        // Tag all operations from a specific package
        String className = method.getDeclaringClass().getPackageName();
        if (className.contains(".orders.")) {
            operation.setDescription(
                    (operation.getDescription() != null ? operation.getDescription() + " " : "")
                    + "[Order Domain]");
        }

        // Add extension field to every operation
        if (operation.getBindings() == null) {
            operation.setBindings(new java.util.HashMap<>());
        }
    }
}
```

--------------------------------

### Display Server Information in Angular Template

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-ui/src/app/components/servers/servers.component.html

This Angular template code iterates over a collection of servers and displays their key, protocol, and host. Ensure the 'servers' observable or array is properly defined in your component.

```html
@for (server of servers() | keyvalue; track server) {

{{ server.key }} {{ server.value.protocol }}

Host

{{ server.value.host }}

}

```

--------------------------------

### @KafkaAsyncChannelBinding Annotation

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Attaches Kafka topic configuration to a method annotation.

```APIDOC
## @KafkaAsyncChannelBinding — Kafka channel (topic) binding

Attaches Kafka topic configuration (partitions, replicas, retention, cleanup policy) to a method annotation.

```java
import io.github.springwolf.bindings.kafka.annotations.*;
import io.github.springwolf.core.asyncapi.annotations.*;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class EventLogConsumer {

    @KafkaListener(topics = "event-log")
    @AsyncListener(operation = @AsyncOperation(channelName = "event-log"))
    @KafkaAsyncChannelBinding(
            topic = "event-log",
            partitions = 6,
            replicas = 3,
            topicConfiguration = @KafkaAsyncChannelBinding.KafkaChannelTopicConfiguration(
                    cleanup = {KafkaAsyncChannelBinding.KafkaChannelTopicConfiguration.CleanupPolicy.DELETE},
                    retentionMs = 604800000L,   // 7 days
                    retentionBytes = -1L,
                    maxMessageBytes = 1048576))
    @KafkaAsyncOperationBinding
    public void consumeEvent(EventPayload payload) {
        // consume
    }
}
```
```

--------------------------------

### Document Primitive Payloads with @AsyncApiPayload

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use @AsyncApiPayload within an envelope class to document primitive or final class payloads when direct Swagger/OpenAPI @Schema annotation is not possible. Ensure the envelope class is used in the @AsyncOperation's payloadType.

```java
import io.github.springwolf.core.asyncapi.annotations.*;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class StringEventConsumer {

    private static final String TOPIC = "string-events";

    // Use an envelope class to document primitive payloads
    static class StringEventEnvelope {
        @AsyncApiPayload
        @Schema(description = "The raw string event value", maxLength = 255, example = "ORDER_CONFIRMED")
        private String payload;
    }

    @KafkaListener(topics = TOPIC)
    @AsyncListener(operation = @AsyncOperation(
            channelName = TOPIC,
            description = "Consumes raw string event messages.",
            payloadType = StringEventEnvelope.class,   // use envelope
            headers = @AsyncOperation.Headers(notUsed = true)))
    @io.github.springwolf.bindings.kafka.annotations.KafkaAsyncOperationBinding
    public void receiveStringEvent(String event) {
        // handle event
    }
```

--------------------------------

### Add Springwolf AMQP Plugin Dependency

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Add the Springwolf AMQP plugin and its binding to your Gradle dependencies to enable integration with AMQP messaging. The UI is optional.

```groovy
dependencies {
    implementation "io.github.springwolf:springwolf-amqp:2.4.0"
    implementation "io.github.springwolf:springwolf-amqp-binding:2.4.0"
    implementation "io.github.springwolf:springwolf-ui:2.4.0"
}
```

--------------------------------

### Configure Async Operation Metadata with @AsyncOperation

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use @AsyncOperation to define channel name, description, payload type, servers, message details, and headers for asynchronous operations. Explicitly override payload types if needed.

```java
import io.github.springwolf.core.asyncapi.annotations.*;
import io.swagger.v3.oas.annotations.media.Schema;

@AsyncOperation(
    channelName = "inventory-updates",         // channel/topic/queue name
    description = "Receives inventory change events.",
    payloadType = InventoryUpdatePayload.class, // explicit override if needed
    servers = {"kafka-server"},                // restrict to specific servers
    message = @AsyncMessage(
            messageId = "InventoryUpdateMsg",
            name = "InventoryUpdate",
            title = "Inventory Update Event",
            contentType = "application/json",
            description = "Signals a change in product inventory."),
    headers = @AsyncOperation.Headers(
            schemaName = "InventoryUpdateHeaders",
            description = "Standard headers",
            values = {
                @AsyncOperation.Headers.Header(
                        name = "event-type",
                        description = "Type of inventory event",
                        value = {"INCREASE", "DECREASE", "RESET"},
                        type = SchemaType.STRING)
            }))
```

--------------------------------

### Add Generic Binding Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-add-ons/springwolf-generic-binding/README.md

Include this dependency in your project to use the Springwolf Generic Binding add-on.

```groovy
dependencies {
    implementation 'io.github.springwolf:springwolf-generic-binding:<springwolf-version>'
}
```

--------------------------------

### Add Optional Springwolf Add-ons

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Incorporate optional Springwolf add-ons for enhanced functionality, such as model converters for common types, JSON schema generation, custom bindings, or Kotlin serialization support.

```groovy
dependencies {
    // Support for MonetaryAmount, UUID, etc.
    implementation "io.github.springwolf:springwolf-common-model-converters:2.4.0"
    // JSON Schema generation from AsyncAPI schemas
    implementation "io.github.springwolf:springwolf-json-schema:2.4.0"
    // Custom bindings for unsupported protocols
    implementation "io.github.springwolf:springwolf-generic-binding:2.4.0"
    // Kotlin serialization model converter
    implementation "io.github.springwolf:springwolf-kotlinx-serialization-model-converter:2.4.0"
}
```

--------------------------------

### Access AsyncAPI Document Programmatically

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Use AsyncApiService to retrieve the complete AsyncAPI document or a scoped view for a specific group name. This is useful for exporting or analyzing the generated API model.

```java
import io.github.springwolf.asyncapi.v3.model.AsyncAPI;
import io.github.springwolf.core.asyncapi.AsyncApiService;
import org.springframework.stereotype.Component;

import java.util.Optional;

@Component
public class AsyncApiExporter {

    private final AsyncApiService asyncApiService;

    public AsyncApiExporter(AsyncApiService asyncApiService) {
        this.asyncApiService = asyncApiService;
    }

    public void exportDocument() {
        // Get the full document
        AsyncAPI document = asyncApiService.getAsyncAPI();
        System.out.println("Channels: " + document.getChannels().keySet());
        System.out.println("Operations: " + document.getOperations().keySet());

        // Get a scoped group document
        Optional<AsyncAPI> ordersGroup = asyncApiService.getForGroupName("OrdersOnly");
        ordersGroup.ifPresent(api ->
                System.out.println("Orders channels: " + api.getChannels().keySet()));
    }
}
```

--------------------------------

### @AsyncOperation Annotation

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Configures metadata for an asynchronous operation, such as channel name, description, and payload type.

```APIDOC
## @AsyncOperation — Operation metadata (embedded annotation)

Inner annotation used inside `@AsyncListener` and `@AsyncPublisher` to configure channel name, description, message metadata, headers, servers, and payload type override.

```java
@AsyncOperation(
    channelName = "inventory-updates",         // channel/topic/queue name
    description = "Receives inventory change events.",
    payloadType = InventoryUpdatePayload.class, // explicit override if needed
    servers = {"kafka-server"},                // restrict to specific servers
    message = @AsyncMessage(
            messageId = "InventoryUpdateMsg",
            name = "InventoryUpdate",
            title = "Inventory Update Event",
            contentType = "application/json",
            description = "Signals a change in product inventory."),
    headers = @AsyncOperation.Headers(
            schemaName = "InventoryUpdateHeaders",
            description = "Standard headers",
            values = {
                @AsyncOperation.Headers.Header(
                        name = "event-type",
                        description = "Type of inventory event",
                        value = {"INCREASE", "DECREASE", "RESET"},
                        type = SchemaType.STRING)
            }))
```
```

--------------------------------

### Add Springwolf Kotlinx Serialization Dependency

Source: https://github.com/springwolf/springwolf-core/blob/main/springwolf-add-ons/springwolf-kotlinx-serialization-model-converter/README.md

Include the necessary dependency in your Gradle build file to enable the Kotlinx Serialization model converter for Springwolf.

```groovy
dependencies {
    implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converters:<springwolf-version>'
}
```

--------------------------------

### @AsyncApiPayload Annotation

Source: https://context7.com/springwolf/springwolf-core/llms.txt

Marks a field within an envelope class to define the actual message payload when it's a primitive or final class.

```APIDOC
## @AsyncApiPayload — Mark payload field in an envelope class

Field-level annotation used when the actual message payload is a primitive or final class (e.g., `String`, `Integer`) that cannot be directly annotated with Swagger/OpenAPI `@Schema`. Wrap the type in an envelope class and mark the field.

```java
import io.github.springwolf.core.asyncapi.annotations.*;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.kafka.annotation.KafkaListener;
import org.springframework.stereotype.Component;

@Component
public class StringEventConsumer {

    private static final String TOPIC = "string-events";

    // Use an envelope class to document primitive payloads
    static class StringEventEnvelope {
        @AsyncApiPayload
        @Schema(description = "The raw string event value", maxLength = 255, example = "ORDER_CONFIRMED")
        private String payload;
    }

    @KafkaListener(topics = TOPIC)
    @AsyncListener(operation = @AsyncOperation(
            channelName = TOPIC,
            description = "Consumes raw string event messages.",
            payloadType = StringEventEnvelope.class,   // use envelope
            headers = @AsyncOperation.Headers(notUsed = true)))
    @io.github.springwolf.bindings.kafka.annotations.KafkaAsyncOperationBinding
    public void receiveStringEvent(String event) {
        // handle event
    }
}
```
```