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.
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.docket.default-content-type | application/json | Content type to use when encoding/decoding a message's payload (example generation). Also supported: text/xml, application/yaml. |
springwolf.docket.id | N/A | The Identifier value represents a unique universal identifier of the application. See Identifier. |
springwolf.docket.group-config | N/A | See Grouping for more details. |
springwolf.endpoint.actuator.enabled | false | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. |
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.payload.extractable-classes.. | N/A | Extract additional payload types. See message payloads for more details. |
springwolf.studio-compatibility | true | Activate tweaks to allow viewing & editing in AsyncAPI studio |
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. |
springwolf.use-fqn | true | Use fully qualified names for the schema classes. Required for publishing with springwolf-ui |
| UI | ||
springwolf.ui.defaults.show-bindings | true | Show bindings by default in the UI. |
springwolf.ui.defaults.show-headers | true | Show headers by default in the UI. |
| Plugin: 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. |
| Plugin: 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. |
| Plugin: 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. |
| Plugin: SNS | ||
springwolf.plugin.sns.publishing.enabled | false | Allow (anyone) to produce SNS messages from the UI. Note that this has security implications |
| Plugin: 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. |
| Plugin: 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. |
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).
Grouping
The standard AsyncAPI document contains all information, including channels, messages, schemas, etc.
A group is a filtered view onto specific parts of the AsyncAPI document.
The group configuration must have a name (group). The info object can be adjusted and at most one matcher can be used:
| Matcher | Description | Example to filter for |
|---|---|---|
channel-name-to-match | List of regular expressions to match the channel name. | Only public channels: channel-name-to-match=public-.* |
message-name-to-match | List of regular expressions to match the message name. | All interactions with a specific payload class: message-name-to-match=.*Vehicle.* |
action-to-match | List of receive, send | Only published messages: action-to-match=send |
Configuration example for the group Only Vehicles to only include classes which contain the word Vehicle in the class name:
springwolf.docket.group-configs[0].group=Only Vehicles
springwolf.docket.group-configs[0].info.description=Group for vehicles.
springwolf.docket.group-configs[0].info.extension-fields.x-apitype=internal
springwolf.docket.group-configs[0].message-name-to-match=.*Vehicle.*
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.