Configuration
Add the following to the spring application.properties file:
# Springwolf - required fields
springwolf.docket.base-package=io.github.springwolf.example
springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0
springwolf.docket.servers.kafka-server.protocol=kafka
springwolf.docket.servers.kafka-server.host=${spring.kafka.bootstrap-servers}
# Springwolf - optional fields
springwolf.enabled=true
springwolf.docket.default-content-type=application/json
springwolf.docket.id=urn:io:github:springwolf:example
springwolf.docket.info.description=Springwolf example project to demonstrate springwolfs abilities
springwolf.docket.info.terms-of-service=http://asyncapi.org/terms
springwolf.docket.info.contact.name=springwolf
springwolf.docket.info.contact.email=example@example.com
springwolf.docket.info.contact.url=https://github.com/springwolf/springwolf-core
springwolf.docket.info.license.name=Apache License 2.0
springwolf.docket.info.x-internal-id=xyz-123
# Springwolf - debugging
logging.level.io.github.springwolf=DEBUG
Properties
base-backage (required)
It's recommended to structure the project such that all consumers and producers (classes containing listener/producer methods) are in the same package - it's not mandatory, and if they're scattered across multiple packages, just provide the highest in hierarchy package that contains all classes.
The base-package will be scanned for classes containing @Component annotated classes (that includes @Service annotated classes) for methods annotated with @JmsListener, @KafkaListener, MessageMapping, @RabbitListener, @SqsListener, @AsyncListener, @AsyncPublisher, etc.
@Configuration classes are scanned for @Bean containing the previously mentioned annotations as well.
Info (required)
The Info object provides metadata about the API (see Info Object.
All provided fields will be present in the generated document, but not all will be displayed in the UI.
Servers (required)
The Server object provides metadata to help the reader understand the protocol, version, login details and more (see AsyncAPI Server Object).
Any name (kafka-server in the example) can be chosen.
An AsyncAPI document can contain more than one server, but it's not common.
As with the Info object, all provided fields will be present in the generated document, but not all will be displayed in the UI.
id
The Identifier value represents a unique universal identifier of the application. See Identifier.
default-content-type
A string representing the default content type to use when encoding/decoding a message's payload. See Default Content Type
The default is application/json and it has an effect on the payload example generation. Also supported: text/xml, application/yaml.
Extension Fields
The AsyncAPI specification allows the definition of additional data fields to extend the specification at certain points (see Specification Extensions ).
Extension Fields may be added to Info, Contact, License and Server objects both via application.properties.
Every custom extension field must begin with x-, for example x-internal-id (see sample configurations above).
Additional application.properties
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 | true | Use fully qualified names for the schema classes. Required for publishing with springwolf-ui |
springwolf.studio-compatibility | true | Activate tweaks to allow viewing & editing in AsyncAPI studio |
springwolf.payload.extractable-classes.. | N/A | Extract additional payload types. See message payloads for more details. |
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. |
| JMS | ||
springwolf.plugin.jms.publishing.enabled | false | Allow (anyone) to produce JMS messages from the UI. Note that this has security implications |
springwolf.plugin.jms.scanner.jms-listener.enabled | true | Enable scanner to find methods annotated with @JmsListener. |
| 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. SpringwolfKafkaProducer demonstrates multiple producer configuration to publish to Avro and Protobuf. |
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. |
| STOMP (WebSocket) | ||
springwolf.plugin.stomp.scanner.stomp-message-mapping.enabled | true | Enable scanner to find methods annotated with @MessageMapping. |
springwolf.plugin.stomp.scanner.stomp-send-to.enabled | true | Enable scanner to find methods annotated with @SendTo. |
springwolf.plugin.stomp.scanner.stomp-send-to-user.enabled | true | Enable scanner to find methods annotated with @SendToUser. |
Actuator support
Springwolf supports exposing the AsyncAPI document as part of Spring Boot’s actuator endpoint.
The AsyncAPI document will then be moved underneath actuators base path, that's /actuator/springwolf.
To enable it, add the spring-boot-actuator dependency first.
Second, enable the actuator endpoint in the application.properties file:
# Move Springwolf endpoint to actuator
springwolf.endpoint.actuator.enabled=true
# Expose Springwolf endpoint in spring
management.endpoints.web.exposure.include=springwolf
If the actuator management port is configured differently than the application port or the actuator base path is changed, then the exposed AsyncAPI document will follow accordingly.
Enabling actuator support for Springwolf will break the Springwolf UI.