Frequently Asked Questions
General
Is Springwolf free & What's the license
Yes, you can use Springwolf for private and commercial purposes as long as you comply to the Apache License 2.0.
Use springwolf-ui
only (without plugins)
You can use springwolf-ui
without any other Springwolf dependency.
springwolf-ui
will fetch any documentation available at the springwolf/docs
path.
It must be in json
format (yaml
isn't supported).
Either create a custom spring controller to serve the file or serve static resources with spring and place AsyncAPI document file called docs
(without file extension) into the folder resources/springwolf
.
Note: springwolf-ui
doesn't support the full AsyncAPI spec.
Springwolf in unit / integration test
See Static Generation.
Troubleshooting
Show debug
output in the logs
Springwolf uses the default logging setup of Spring Boot.
To enable DEBUG
output, add the following line to the application.properties
:
logging.level.io.github.springwolf=DEBUG
The Springwolf UI isn't showing
When the springwolf-ui
dependency is added, the UI should be visible at http://localhost:8080/springwolf/asyncapi-ui.html.
If not, whether
-
you customized the spring
context-path
setting -
static assets are being served at all. See the code below:
@Configuration
public class WebConfig implements WebMvcConfigurer {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry
.addResourceHandler("/**")
.addResourceLocations("classpath:/META-INF/resources/", "classpath:/resources/", "classpath:/static/", "classpath:/public/");
}
}Taken from Discord Chat
-
spring-security (or similar) denies access the URLs (HTTP 403). Check
CustomWebSecurityConfigurerAdapter
inspringwolf-kafka-example
.
Unable to publish message from the UI
Publishing messages from the UI is disabled by default due to security concerns. Springwolf doesn't offer authentication nor authorization, anyone can publish messages to (production) channels.
Check the configuration to enable this feature.
Be sure to enable fully qualified names (use-fqn
) as well.
Spring Security allows to limit access to authorized users.
Classes have fully qualified names (io.springwolf.package.ClassName
)
Disable the fully qualified class name (FQN) option (springwolf.use-fqn=false
).
Only one of multiple classes with the same name (different package) is detected
Enable the fully qualified class name (FQN) option (springwolf.use-fqn=true
).
Springwolf interferes with OpenAPI documentation
Springwolf uses swagger-core
to analyze classes, which is used by some OpenAPI libraries like springdoc-openapi
.
swagger-core
configuration is partly global and can't be isolated.
Options:
- Use the same settings in Springwolf and the other library (including the fully qualified class name (FQN) option).
- Don't run Springwolf and the other library at the same time, for example by generating the documentation at build time.
Generic types (List) don't contain item properties
Due to java type erasure some generic type information is lost during runtime.
Defining your own type can resolve this.
Change
public void sendMessage(List<String> msg) {}
to
class ListWrapper extends ArrayList<String> {}
public void sendMessage(ListWrapper<String> msg) {}
Consumers are detected multiple times (with different payloads)
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together. This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
Springwolf uses on scanners to find all consumer and producers in your application. Most likely two scanners found your consumer/producer each. See configuration to disable scanners.
Usage Patterns
How to access the generated documentation within java
Use the AsyncApiService
to access the generated documentation.
How to customize the generated documentation
See the customization page
Release Notes / Migration Guide / Updating / Upgrading
Releases are managed in GitHub Releases, which feature noteworthy changes, the full changelog and notes on how to migrate.
Since each release has a git tag, the Springwolf examples for each plugin showcase the use of Springwolf for any previous version.
How to migrate from Springwolf 0.18.0 to 1.0.0
See Release 1.0.0.
How to migrate from the deprecated AsyncApiDocket
bean to Spring properties
See Issue #445.
Is Spring Boot 2.X supported
You can use an older version of Springwolf, which is build to support Spring Boot 2.X. However, these versions don't get any updates.
Last versions to support Spring Boot 2.X:
springwolf-amqp:0.6.0
springwolf-cloud-stream:0.1.0
springwolf-core:0.6.0
springwolf-kafka:0.10.0
springwolf-ui:0.6.0