DOCSEARCHbyAlgolia
Submit Docs

Springwolf Documentation

website·Indexed 32 days ago

https://www.springwolf.dev/

A tool for Spring applications that automatically generates AsyncAPI documentation using existing code metadata. It features native support for various protocols, auto-detection of listeners and producers, and customizable documentation via AsyncApiCustomizer and OperationCustomizer.

Tokens
9.4K
Snippets
49
Records
77
Agent score
65%

What's inside Springwolf

  1. Overview of Springwolf for Spring Boot asynchronous APIs

    Springwolf is a tool for Spring Boot projects that provides auto-generated documentation for asynchronous APIs (such as AMQP, JMS, Kafka, SNS, SQS, and STOMP/WebSocket). It is compliant with the AsyncAPI specification, bringing a similar experience to OpenAPI/Swagger but for event-driven architectures. When integrated into a project using annotation-based listeners (e.g., @KafkaListener, @RabbitListener), Springwolf automatically provides:

    1. An endpoint that returns an AsyncAPI document describing the asynchronous API.
    2. A web UI for developers, QA, and clients to view the API.
    3. The ability to publish messages to the asynchronous API via the UI.
    @Service
public class ExampleConsumer {

    @KafkaListener(topics = "example-topic")
    public void receiveExamplePayload(ExamplePayloadDto payload) {
        // Do something with payload
    }

}

  2. Auto-detect message consumers in Springwolf

    Springwolf provides built-in support to automatically detect listeners for supported protocols. If the following annotations are used in your project, they are detected automatically without additional configuration: @JmsListener, @KafkaListener, @MessageMapping, @RabbitListener, @SqsListener, @SendTo, and @SendToUser. Note that Springwolf only scans for methods located within the configured base-package.

  3. Generate AsyncAPI documentation for Spring applications with Springwolf

    Springwolf automatically creates API documentation for Spring applications by leveraging metadata already present in the code. The generated documentation is fully compliant with the AsyncAPI v3 specification. It can be integrated into CI/CD pipelines for publishing to tools like Backstage.

  4. Implement a custom protocol scanner plugin

    Springwolf uses a plugin architecture to support different protocols, orchestrated by springwolf-core via Spring dependency injection. To create a custom scanner plugin for a new protocol, the plugin must implement the ChannelsScanner interface.

  5. Understand Springwolf internal architecture and document generation

    Springwolf works by using scanners to identify defined consumers and producers within a Spring Boot application upon startup. It extracts channels, topics, and payload types to merge them into an AsyncAPI conform document. This document is served via an endpoint and rendered by the Springwolf UI. If publishing is enabled, the UI allows users to send messages through an endpoint, which Springwolf then forwards to the protocol-specific producer.

  6. Improve documentation for external classes using ModelConverters

    ModelConverters allow developers to improve the documentation of classes that cannot be modified directly (e.g., classes from external libraries). ModelConverters follow the same plugin model as scanners.

  7. Verify API documentation changes with unit tests

    Springwolf allows the use of unit tests to verify the generated documentation, enabling developers to detect unexpected changes or ensure expected updates are present.

  8. Modify the final AsyncAPI document using AsyncApiCustomizer

    Implement the AsyncApiCustomizer interface to modify the AsyncAPI document after Springwolf has completed scanning and building the document. This is the final interception point before the document is served to the user.
    @Component
public class AsyncApiTitleCustomizer implements AsyncApiCustomizer {
    @Override
    public void customize(AsyncAPI asyncAPI) {
         asyncAPI.setVersion("3.0.0");
         asyncAPI.getInfo().setTitle("Title set through customizer");
    }
}

  9. Customize AsyncAPI Operation objects using OperationCustomizer

    Implement the OperationCustomizer interface to modify an Operation object after Springwolf has scanned an annotated method and extracted its data. Multiple implementations can be used; their execution order is controlled via the Spring @Order annotation.
    @Component
public class TagCustomizer implements OperationCustomizer {

    @Override
    public void customize(Operation operation, Method method) {
        KafkaListener annotation = AnnotationScannerUtil.findAnnotation(KafkaListener.class, method);
        if (annotation != null && "true".equals(annotation.batch())) {
            Tag tag = new Tag();
            tag.setName("batch");

            operation.getTags().add(tag);
        }
    }
}

  10. Implement custom channel detection using ChannelScanner

    Implement the ChannelScanner interface to add support for protocols not currently supported by Springwolf. When implementing a custom scanner, ensure all payloads are registered in the ComponentsService.

  11. Document messages using @AsyncOperation and @AsyncMessage

    Springwolf maps the message part of the AsyncAPI operationObject as a messageObject. You can define a message within the @AsyncOperation annotation using the message field with @AsyncMessage(). This allows you to specify a unique message ID, name, content type, and description.
    @AsyncPublisher(operation = @AsyncOperation(
        channelName = "example-producer-topic",
        description = "Customer uploaded an example payload", // Optional
        payloadType = ExamplePayloadDto.class, // Optional. Overwrites the detected payload
        message = @AsyncMessage( // Optional
                messageId = "my-unique-id",
                name = "ExamplePayloadDto",
                contentType = "application/vnd.aai.asyncapi+json;version=3.0.0",
                description = "Example payload model for sending messages"
        )
))
public void sendMessage(ExamplePayloadDto msg) {
    // do work
}

  12. Document message producers using @AsyncPublisher

    Since producers (like KafkaTemplate) are defined imperatively, Springwolf cannot automatically detect their metadata. Use the @AsyncPublisher annotation on the publisher method to explicitly add it to the generated AsyncAPI document. Springwolf extracts the payload type from the method arguments. Note that the method must be located within the configured base-package to be discovered.
    @AsyncPublisher(operation = @AsyncOperation(
        channelName = "example-producer-topic",
        description = "Customer uploaded an example payload", // Optional
        servers = {"kafka-server"} // Optional
))
@KafkaAsyncOperationBinding
public void sendMessage(ExamplePayloadDto msg) {
    // do work
}