Automated documentation for event-driven applications built with Spring Boot
Springwolf 1.2.0 is out! Thanks to all our contributors!
Besides a couple of bug fixes and small improvements, these are the noteworthy new features:
Kafka & Google PubSub Binding The Kafka bindings have been updated to spec version 0.5.0 and support for Google PubSub has been updated to also support channel bindings. Take a look at the binding artifacts for details.
Kotlinx Serialization Add-on The add-on has been extended to support polymorphism and received some smaller bugfixes.
Support for XML attributes The support for XML examples has been extended to also support XML attributes.
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v1.1.0...v1.2.0
Springwolf 1.1.0 is out! Thank you to all contributors.
It contains a couple bug fixes after the big 1.0.0 release last month, next to the following noteworthy new features:
springwolf-googlepubsub-binding artifactspringwolf-(sns|sqs)-binding). We consider extract all bindings to own artifacts, which would be included by default in the plugin artifacts. The intention is to offer a more light-weight springwolf experience for users that only want to use annotations without auto-detection of listeners - and thereby avoid the additional dependencies as well@SerialName annotation. This is packaged in springwolf-kotlinx-serialization-model-converter
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v1.0.0...v1.1.0
We are extremely happy to release Springwolf v1.0.0, a major milestone for us 🥳 It contains a lot of refactorings, some simplifications and the update to AsyncAPI spec 3.0 - contributed by @ctasada
The new AsyncAPI 3.0 specification was released at the end of 2023. It includes a new structure, more bindings and resolved the confusion around publish & subscribe.
@ctasada wrote the new springwolf-asyncapi artifact, which is a Java implementation of the spec targeted for Springwolf. With 14.320 additions, it is the largest contribution in the Springwolf history by far!
As announced in earlier releases, the AsyncApiDocket is not available for configuration anymore. We implemented your feedback and suggestions to ensure the new method using Spring application properties is as powerful (See discussion in issue: https://github.com/springwolf/springwolf-core/issues/445 )
Springwolf-ui got a facelifting as well.
Check out the demo at https://demo.springwolf.dev/springwolf-ui/asyncapi-ui.html
The examples can be rendered as yaml and xml (besides json, which stays the default). This can be configured via the contentType attribute of the @AsyncMessage annotation.
Also, polymorphic types (@JsonTypeInfo) which are present as the field discriminator are rendered correctly now, resolving the long outstanding bug https://github.com/springwolf/springwolf-core/issues/160.
io.github.stavshamir.springwolf to io.github.springwolf. Most Springwolf annotations can be found in io.github.springwolf.core.asyncapi.annotations
logging.level.io.github.springwolf=DEBUG - in case you use this in your application.springwolf.use-fqn was changed to true. To go back to the old behaviour, specify springwolf.use-fqn=false.SqsQueueBindings and SqsBindings contain new require values, which must be provided.@AsyncListener & @AsyncPublisher annotation.springwolf.docket.servers application.properties, as the fields are called host and protocol now.AsyncApiCustomizer, some fields might be moved due to the new AsyncAPI 3.0 spec and must be adjusted.Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.18.0...v1.0.0
v0.18.0 has been released, including new features and fixes. Our focus has been on refactorings and we are working hard to upgrade to AsyncAPI 3.0 in the next release - which will include breaking changes.
We improved support for Avro and Protobuf by removing extraneous fields related to the wire format. At the same time, our kafka demo application show cases this, including the ability to consume and produce messages - all in one application. See CustomSpringwolfKafkaProducer for configuration.
One issue from the beginning was the inability to enhance documentation on final classes as the @Schema annotation could not be attached. Now, by defining an envelope class and marking the property with @AsyncApiPayload, also final classes can be document. See the StringConsumer for more details.
Not everyone is using @Component or related annotations to mark classes for Spring. Now, Springwolf does also detect marked listener and publisher methods in classes, which are instantiated as Spring beans via configuration classes.
@AliasFor by @timonback in https://github.com/springwolf/springwolf-core/pull/519
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.17.0...v0.18.0
v0.17.0 has been released with two new artifacts and many smaller improvements.
Thank you for your feedback on the AsyncApiDocket deprecation (#445). A couple improvements are included in this release while we try - with your help - to address the remaining ones.
Users of the kafka plugin will have to update to Spring Boot 3.2. due to a change in an underlying library.
JMS PluginBig Shout-out to @krzysztofxkwiecien for creating a new plugin to natively detect the @JmsListener along the AsyncAPI JMS binding.
json-schema Add-onNext to the AsyncAPI schema, which is very similar to the OpenAPI schema, json-schema is also commonly used in applications.
The newly added add-on translates the detected AsyncAPI schema to json-schema schema.
Want to try it? Just add the add-on. Everything else is handled by the library. More details.
In advanced use-cases, an application is connected to multiple message brokers. How to indicate which broker a listener belongs to?
Specify the servers property of the AsyncListener / AsyncPublisher annotation.
Springwolf tries to extract the payload of listeners and publishers. Not all methods pass in the type directly, and instead it can be wrapped like List<Message<String>> where the actual payload is String.
In earlier version, the classes like List were hard-coded to be extracted. Now, the classes to extract can be specified per configuration - to also support custom generic classes. More details will follow on springwolf.dev.
Please note that we release this in beta (we may completely change how this is configured) and are happy to listen to your feedback.
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.16.0...v0.17.0
We are happy to announce another release thanks to many changes made by our contributors. This release marks a milestone for Springwolf, as we just achieved 200 stargazers on GitHub.
A while ago we introduced configuration via Spring properties. We view this as a more powerful and natural way of configuring applications in the SpringBoot ecosystem. In last couple of releases we focused on this new way of configuring Springwolf and maintaining the old way of configuring the AsyncApiDocket has become cumbersome.
Check the Quickstart to see how you can migrate.
Using springwolf.use-fqn=true, schema names will be generated using the fully qualified class name. This is deactivated due to backward compatibility by default, but is required to continue to use the publishing functionality.
We added a new Plugin to support documentation for producers that are using the SNS protocol.
Because Springwolf does not support all binding properties, the generic-binding add-on was created. It allows to add all properties without validation according to the AsyncApi specification.
Special thanks to @tvahrst for transforming Springwolf into a more modern Spring Boot library:
@ConditonalOnMissingBean)Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.15.1...v0.16.0
We are happy to announce another release thanks to many changes made by our contributors.
(releasing 0.15.0 failed. Re-releasing as 0.15.1)
We finally removed swagger-inflector dependency after successfully replacing it in the last releases. This resolves multiple dependency issues with old javax imports and duplicate swagger-... libraries.
Now, it is possible to expose the /springwolf/docs as part of Spring Actuators. This removes the endpoint from the normal application and instead moves it to the internals. It must be enabled, more details on the website.
Previously, we created new Objectmappers statically to publish messages from the ui. To resolve #357 , the spring managed ObjectMapper is injected. This requires an ObjectMapper bean, which is usually created by Spring automatically. When you encounter a NoSuchBeanException, you can create one manually with:
@Bean
public ObjectMapper objectMapperBean() {
return new ObjectMapper();
}
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.14.0...v0.15.0
We are happy to announce another release thanks to many changes made by our contributors.
ExampleJsonGenerator fixedThe ExampleJsonGenerator introduced in the last release included some bugs, which we have addressed. Thank you for the feedback and test cases that we have added as well. If you find further issue, please continue to report them.
We decided to continue to stick with swagger-inflector as a fallback for this release, but plan to remove it in the next release.
@ConditionalOnProperty support@jmwestbe added in #340 correct handling for @ConditionalOnProperty annotations. Springwolf does respect whether methods annotated with ...Listeners are actually activated now.
We expanded our range of supported protocol to AWS SQS. Add the springwolf-sqs plugin to benefit from auto-detection of @SqsListener or use @AsyncPublisher with @SqsAsyncOperationBinding.
See the example for more details.
@AsyncOperationBinding annotation to simplify the creation of new operation bindings by @ctasada in https://github.com/springwolf/springwolf-core/pull/296
Full Changelog: https://github.com/springwolf/springwolf-core/compare/v0.13.0...v0.14.0
We are happy announce another release thanks to many changes by our contributors.
To avoid confusion for our users and to reduce complexity in their dependency management, we aligned all artifacts to be release together and have the same version.
Please be aware that some artifacts in this release might skip several minor versions.
Until now, Springwolf was using an implementation from swagger-inflector to generate example values. Unfortunately swagger-inflector is rarely getting security updates. Therefore we decided to remove the dependency from Springwolf and replace its functionality with our own implementation.
We decided to deprecate the usage of swagger-inflector for generating example values for this release. Please create a new issue if you have any problems or unexpected output. In the meantime you can set Springwolf to continue to use the old behavior by setting springwolf.example-generator=swagger-inflector-json.
Please be aware that we plan to remove the old behavior with the next release.
By default Springwolf loads during application startup, which can slow down the startup of large applications. It is now possible to defer the initialization of Springwolf until the application is ready. Check the documentation for the property springwolf.init-mode for further information.
In case Springwolf does not produce the AsyncAPI document you need or expect, it is now possible to customize it yourself. Refer to the documentation for further details.
Full Changelog: https://github.com/springwolf/springwolf-core/compare/springwolf-core-0.11.1...v0.13.0
Patch release particular for maven users (Bug report: https://github.com/springwolf/springwolf-core/issues/232)
Full Changelog: https://github.com/springwolf/springwolf-core/compare/springwolf-core-0.11.0...springwolf-core-0.11.1