feat: create new annotation for classes that allows you to have multiple channels within

[azizabah]

What

This change allows for a new annotation, @AsyncApiDocumentation, to be added to a class. This then allows you to have multiple "Channels" within that class that will each be processed for documentation correctly.

Why

This will allow @channel documentation to be used on functions that create beans (for example) to keep verboseness to a minimum in a code base. This fixes #75

How

A new annotation is created and it it finds classes with that annotation and then looks for functions within that have been annotated with Channel and builds documentation based on that.

[github-actions]

Welcome to AsyncAPI. Thanks a lot for creating your first pull request. Please check out our contributors guide useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[lorenzsimon]

Hi @azizabah, thanks for the PR. To support this feature you would need to refactor the annotation scanner / processor first. The logic lives in the context module here. In short, we currently only check classes for the @Channel annotation because we don't rely on Spring annotation processor and would need to check all functions of all classes to find it otherwise.
Feel free to suggest another method for it though :)

[azizabah]

@lorenzsimon Thanks for the pointer. I will take a look there.

[azizabah]

@lorenzsimon - Updated with a unit test showing it can handle both now.

There was a breaking change introduced in Spring Boot 3.4.0 related to mockMVC so that is why I version locked it to 3.3.5 as part of this PR. I would suggest we tackle that as a separate PR.

[lorenzsimon]

Almost there 🤏

[lorenzsimon]

sorry, there is actually still something missing: you see that componentToChannelMapping above? you have to add the the channels you find in the class to this map. because it is used to bind the channel components to the actual channel top level object. not sure if that makes sense. but currently you would only add the channels under components.channels but you also want them in asyncapi.channels.

[azizabah]

@lorenzsimon - Ok. I wasn't sure what the purpose of that map was. I will add it.

[azizabah]

Updated.

[lorenzsimon]

AsyncApiComponent annotation does not need the value property. You need to map the value of the channel annotation itself. In your example, some/{parameter}/channel should be the name of the channel. And this is what the bind method is doing. It checks what the value property is, uses this as the name of the channel and then references the channel component based on the class name (or the function name in your case).

{
  "channels": {
    "some/{parameter}/channel": ...
  }
}

I think we should add it to the spring integration test:

kotlin-asyncapi/kotlin-asyncapi-spring-web/src/test/kotlin/org/openfolder/kotlinasyncapi/springweb/controller/AsyncApiControllerIntegrationTest.kt

Line 177 in df0aa85

val expected = TestUtils.json("async_api_annotation_integration.json")

[azizabah]

@lorenzsimon - AsyncApiComponent is the class though not the function, we changed the behavior at your request. There can be multiple channels inside an AsyncApiComponent so you want me to replicate that logic to populate this map?

Something like this (which doesn't work):

is AsyncApiComponent -> asyncApiComponentProcessor.process(annotation, clazz).also { processedComponents ->
                        processedComponents.channels?.forEach { (channelName, _) ->
                            componentToChannelMapping[channelName] = channelName
                        }
                    }

[azizabah]

Ok. Looking at the integration test was the clue I needed to find the issues with my implementation. This should be resolved now.

[lorenzsimon]

btw sorry for the merge conflicts. I will resolve them once the PR is ready :)

[lorenzsimon]

Let me know if you want me to finish the PR. I would have some time next weekend.

[lorenzsimon]

Should be TestChannel

[azizabah]

No - in places where the channel is inside a class, it should be the value of the annotation not the name of the class. https://github.com/azizabah/kotlin-asyncapi/blob/bc83ab4f5825d56f7741f126fce481bad57e8c6b/kotlin-asyncapi-spring-web/src/test/kotlin/org/openfolder/kotlinasyncapi/springweb/controller/AsyncApiControllerIntegrationTest.kt#L251

If you do it as the value of the class, you will run into conflicts when you have multiple inside the same class which is the exact functionality this entire PR is about.

[lorenzsimon]

You could iterate over the class functions here already. Then you can change the component processor to process the functions instead of the class: private val asyncApiComponentProcessor: AnnotationProcessor<AsyncApiComponent, KFunction<*>>
Also you need to use componentToChannelMapping[function.name] = annotation.value because there could be multiple channels in the class.

[azizabah]

I am handling iterating over the values inside the AsyncApiComponentProcessor. If you look at that code, you can also see, I'm setting the value to the annotation value not the function name. I think this is clearer for users and provides a better experience than forcing the function name to be there.

[lorenzsimon]

@azizabah can you resolve the merge conflicts? I don't have write access to your fork.

[azizabah]

can you resolve the merge conflicts? I don't have write access to your fork.

Merges resolved @lorenzsimon