AsyncApiDocket bean deprecation

[sam0r040]

Dear users of Springwolf,

after the deprecation of the AsyncApiDocket bean, some people have already asked us about migration options for their use cases.
Therefore, we will gather all information about it in this issue. We will try to address your concerns before we remove the AsyncApiDocket bean.

If you have questions please add a comment and link.

1. Add mandatory properties to application properties

springwolf.docket.base-package=io.github.stavshamir.springwolf.example.consumers

springwolf.docket.info.title=${spring.application.name}
springwolf.docket.info.version=1.0.0

springwolf.docket.servers.kafka.protocol=kafka
springwolf.docket.servers.kafka.url=${kafka.bootstrap.servers:localhost:29092}

Source: https://www.springwolf.dev/docs/quickstart

Map all entries of the docket to its Spring properties equivalent. The Spring properties equivalent start with springwolf.docket..
Example: The title within the info object is springwolf.docket.info.title=my title

2. Convert consumers and/or producers to annotations

Consumers and/or producers defined in the AsyncApiDocket have to be converted to the @AsyncListener and/or @AsyncPublisher annotation approach. See the Consumers and Producers page on how to map the properties.

• https://www.springwolf.dev/docs/configuration/documenting-consumers
• https://www.springwolf.dev/docs/configuration/documenting-producers

You can use the Spring Expression language to look up values from application properties at runtime. For example:

@AsyncPublisher(
     operation = @AsyncOperation(
            channelName = "${spring.application.name}", //put variable here
            description = "More details for the outgoing topic"
     )
)
@KafkaAsyncOperationBinding
public void send(@Nonnull final String message) {
     send(message, Collections.emptyList());
}

Technically, it does not matter on which method you put those annotations. If you do not have an explicit method for consuming/producing, you can put the annotation on any method you like. Just make sure you specify the payloadType property.

[timonback]

Deprecation PR: #422
Known limitations:

• MethodLevelListener does not handle different payloads for same topic/queue #446
• Find Listener Methods on Beans that are created by configuration classes #462

[hirth-abi]

I could migrate successfully to the new annotation based approach, thanks for the hints in this ticket. It would be nice if also subpackages within the base-package would be scanned, since our consumers/producers are in subpackages and I had to add several methods in the base package just for documentation.

[timonback]

I could migrate successfully to the new annotation based approach, thanks for the hints in this ticket. It would be nice if also subpackages within the base-package would be scanned, since our consumers/producers are in subpackages and I had to add several methods in the base package just for documentation.

All packages below and including base-package are scanned. Each of our examples projects find the producers/consumers in the sub-package consumers and producers respectively.
Do you have an example so we can replicate it?

By increasing the log level, you should find log entries containing Scanning class?

# For debugging purposes
logging.level.io.github.stavshamir.springwolf=DEBUG

[jenarp]

I've noticed that Springwolf annotations are recognized only when they are placed within classes annotated with @Component, @Service, and similar.
However, the class that contains my send() method, which I want to document with @AsyncPublisher, lacks such annotations. Instead, this class is instantiated via a @Bean definition in a @Configuration class. Consequently, it is not detected by the Component Scanner.
I'm uncertain whether this is a unique issue with my application or a broader problem. It would be great if this could be addressed in the next release, as currently, I am unable to utilize Springwolf effectively.
The only workaround seems to be customizing my Async API specification manually with AsyncApiCustomizer.

[hirth-abi]

All packages below and including base-package are scanned. Each of our examples projects find the producers/consumers in the sub-package consumers and producers respectively. Do you have an example so we can replicate it?

You're right, I've found the configuration error on my side 👍

I've detected a minor issue, if we implement interfaces and document them, an unexpected documentation is also added for the interface method (an easy workaround is to define the payloadType redundantly). Here is an example: bfd9f17

[timonback]

Hi @hirth-abi,
@sam0r040 and me looked into it and addressed it in #463

Hi @jenarp,
we created #462 to track your suggestion

[silentrobi]

We are having problem generating document when updating springwolf library bacause of our recent migration to 3.1.x.
In our project a custom generic abstract class is being used which is extended by other classes and the abstract class has core sendPublish method. As the abstract class is not annotated with spring @Component, Springwolf-kafka can't detect @AsyncPublisher annotation which is very annoying. This will force us to change the core implementation. Besides, generated publishers through AsyncApiDocket (second approach which we had been using before it became deprecated) doesn't seems to be working anymore. springwolf-ui doesn't show all the publishers and missing other information.
springwolf-kafka & springwolf-ui --> 0.17.0

[timonback]

Hi @silentrobi

In our project a custom generic abstract class is being used which is extended by other classes and the abstract class has core sendPublish method. As the abstract class is not annotated with spring @Component, Springwolf-kafka can't detect @AsyncPublisher annotation which is very annoying.

We recently improved the handling of detecting on interfaces in #475
Can you try the current -snapshot version or adapt one of the example projects so that we can reproduce it?

springwolf-ui doesn't show all the publishers and missing other information.

Is the @KafkaAsyncOperationBinding missing? https://www.springwolf.dev/docs/configuration/documenting-bindings
An excerpt from the asyncapi.json/yaml channels section would help.

[timonback]

Yesterday, we also resolved the second outstanding limitation #462 (detect annotations in classes that are instantiated via @Bean methods in @Configuration classes).

@jenarp, @hirth-abi Feel free to try the current -SNAPSHOT build to verify and let us know whether something is missing.

[jenarp]

Hi @timonback,
it works! My @AsyncPublisher annotation is scanned, now!
Thx for your effort!

[hirth-abi]

Hi @timonback 0.17.0 was already working fine and the snapshot continues to do so.

Perhaps just a question, I wanted to add the first time a description to a message, and @AsyncOperation.description seems to be ignored (for consumers and publishers, in the generated JSON file and the UI), is this currently expected?

[timonback]

Great to hear.

That would be a bug if the description is ignored.
In our example, it seems to work: springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/kafka/producers/NestedProducer.java

[timonback]

1.0.0 does not contain the AsyncApiDocket anymore.
More details on how to migrate are documented in the gh release notes.

Feel free to open an issue, if you encounter any issues.