Springwolf

Springwolf is a tool for automated documentation of event-driven applications built with Spring Boot. It leverages existing listener annotations (such as @KafkaListener, @RabbitListener, @SqsListener, etc.) to automatically generate documentation following the AsyncAPI specification.

Key features include:

• Automated AsyncAPI Generation: Exploits existing consumer endpoint descriptions to create schema definitions.
• Integration Ready: Generated AsyncAPI documentation can be shared as json/yaml files or integrated into API hubs like Backstage.
• Springwolf UI: A web interface (similar to Springfox) that allows for easy publishing of auto-generated payload examples, enabling one-click message publishing for testing and debugging.

The Springwolf Generic Binding Add-on is a module designed to provide a generic way to document bindings. It is specifically intended for:

• Documenting fields not yet supported by Springwolf or the AsyncAPI specification.
• Documenting vendor-specific protocols or properties.

It acts as an escape hatch for customization when standard AsyncAPI bindings are insufficient.

When the springwolf-json-schema add-on is active, an x-json-schema field is automatically added to every Schema object in your OpenAPI specification. This field contains the corresponding JSON Schema draft-07 definition for that specific schema.

{
  "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"
    }
  }
}

The Springwolf Kafka Plugin automates the creation of AsyncAPI documents by scanning your Spring Boot application for Kafka-related annotations. It specifically extracts metadata from:

• @KafkaListener methods
• @KafkaHandler methods located within classes annotated with @KafkaListener.

The STOMP example demonstrates specific messaging patterns using the following paths and prefixes:

• Endpoint Connection: Use the /myendpoint path to connect to the application.
• 1-on-1 Communication: Use the /queue prefix for direct client-to-server or server-to-client messaging.
• Broadcasting: Use the /topic prefix to broadcast messages to all connected clients.

The springwolf-kotlinx-serialization-model-converters add-on allows Springwolf to respect kotlinx.serialization annotations when generating AsyncAPI schemas. Specifically, it uses the @SerialName annotation to determine the property names in the generated schema, ensuring that the schema matches the serialized JSON format rather than the Kotlin property names.

@Serializable
data class SomeData(
    @SerialName("id_value")
    val id: Int,
    @SerialName("some_name")
    val name: String,
    @SerialName("color_value")
    val color: Color,
)

After configuration, you can verify the documentation is working by accessing the following endpoints:

1. If springwolf-ui is included: Access the UI at http://localhost:8080/springwolf/asyncapi-ui.html.
2. If springwolf-ui is NOT included: Access the raw documentation at http://localhost:8080/springwolf/docs.

To use the SNS plugin, add the following dependencies to your project. Replace <springwolf-version> with your current Springwolf version. It is recommended to include the springwolf-ui dependency to view the documentation via a web interface.

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>
}

To enable automated AsyncAPI documentation generation for Spring Boot applications using RabbitMQ (@RabbitListener), add the springwolf-amqp dependency. You can optionally include springwolf-ui to provide a visual interface for the generated documentation.

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>'
}