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

azizabah · 2024-12-05T16:39:38Z

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 · 2024-12-07T19:22:10Z

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 · 2024-12-09T19:07:53Z

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

azizabah · 2024-12-10T18:23:33Z

@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.

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt

… the correct classes.

lorenzsimon

Almost there 🤏

...annotation/src/main/kotlin/org/openfolder/kotlinasyncapi/annotation/AsyncApiDocumentation.kt

lorenzsimon · 2024-12-11T18:50:22Z

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt

@@ -81,6 +83,7 @@ class AnnotationProvider(
                        componentToChannelMapping[clazz.java.simpleName] =
                            annotation.value.takeIf { it.isNotEmpty() } ?: clazz.java.simpleName
                    }
+                    is AsyncApiComponent -> asyncApiComponentProcessor.process(annotation, clazz)


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.

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

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")

@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 } }

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

…nnel behavior. added value attribute to AsyncApiComponent for parity.

lorenzsimon · 2024-12-15T17:06:31Z

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

…ent and for Channel annotations to handle the fact that not all of them will be named based on their class and that will only happen if they target a class instead of a function.

lorenzsimon

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

lorenzsimon · 2024-12-22T08:02:03Z

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt

+                        if (clazz.annotations.any { it is Channel }) {
+                            componentToChannelMapping[clazz.java.simpleName] =
+                                annotation.value.takeIf { it.isNotEmpty() } ?: clazz.java.simpleName
+                        }
+                    }


Why is this if check needed? We already made sure that class is annotated with @Channel in the flatMap step before.

lorenzsimon · 2024-12-22T08:04:01Z

...ing-web/src/main/kotlin/org/openfolder/kotlinasyncapi/springweb/AsyncApiAutoConfiguration.kt

@@ -102,6 +104,10 @@ internal open class AsyncApiAnnotationAutoConfiguration {
    open fun channelProcessor() =
        ChannelProcessor()

+    @Bean
+    open fun asyncApiDocumentationProcessor() =


Suggested change

open fun asyncApiDocumentationProcessor() =

open fun asyncApiComponentProcessor() =

lorenzsimon · 2024-12-22T08:22:17Z

kotlin-asyncapi-spring-web/src/test/resources/async_api_component_annotation_integration.json

+      }
+    },
+    "channels": {
+      "my/channel": {


Should be TestChannel

lorenzsimon · 2024-12-22T08:28:57Z

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt

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


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.

allow annotation to target function also.

cf25fe0

github-actions bot reviewed Dec 5, 2024

View reviewed changes

azizabah marked this pull request as ready for review December 5, 2024 17:07

azizabah requested review from lorenzsimon, sueskind and gimlet2 as code owners December 5, 2024 17:07

Charles Bazeley added 2 commits December 10, 2024 13:18

add support for channel on functions instead of just classes.

7bb9a5b

Merge branch 'cbaz/new-build' into azizabah/add-channel

c45fba1

lorenzsimon reviewed Dec 10, 2024

View reviewed changes

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt Outdated Show resolved Hide resolved

...ntext/src/main/kotlin/org/openfolder/kotlinasyncapi/context/annotation/AnnotationProvider.kt Outdated Show resolved Hide resolved

split into a separate processor with new annotation to handle finding…

e6c5479

… the correct classes.

azizabah changed the title ~~feat: allow annotation to target function also.~~ feat: create new annotation for classes that allows you to have multiple channels within Dec 10, 2024

match previous white space

f85697d

lorenzsimon reviewed Dec 11, 2024

View reviewed changes

...annotation/src/main/kotlin/org/openfolder/kotlinasyncapi/annotation/AsyncApiDocumentation.kt Outdated Show resolved Hide resolved

...annotation/src/main/kotlin/org/openfolder/kotlinasyncapi/annotation/AsyncApiDocumentation.kt Outdated Show resolved Hide resolved

Charles Bazeley added 2 commits December 11, 2024 13:35

name updates per PR comments.

1a2a12f

fix annotation location

2d97e67

lorenzsimon reviewed Dec 11, 2024

View reviewed changes

add AsyncApiComponent population of channel map behavior to match Cha…

6e158c4

…nnel behavior. added value attribute to AsyncApiComponent for parity.

change how the map is populated for channels found via AsyncApiCompon…

7a428bd

…ent and for Channel annotations to handle the fact that not all of them will be named based on their class and that will only happen if they target a class instead of a function.

azizabah requested a review from lorenzsimon December 19, 2024 14:41

lorenzsimon changed the base branch from master to dev December 22, 2024 07:58

lorenzsimon reviewed Dec 22, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

azizabah commented Dec 5, 2024 •

edited

Loading

github-actions bot left a comment

lorenzsimon commented Dec 7, 2024

azizabah commented Dec 9, 2024

azizabah commented Dec 10, 2024

lorenzsimon left a comment

lorenzsimon Dec 11, 2024

azizabah Dec 11, 2024

azizabah Dec 11, 2024

lorenzsimon Dec 13, 2024

azizabah Dec 17, 2024

azizabah Dec 17, 2024

lorenzsimon commented Dec 15, 2024

lorenzsimon left a comment

lorenzsimon Dec 22, 2024

lorenzsimon Dec 22, 2024

lorenzsimon Dec 22, 2024

lorenzsimon Dec 22, 2024

	open fun asyncApiDocumentationProcessor() =
	open fun asyncApiComponentProcessor() =

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

Are you sure you want to change the base?

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

Conversation

azizabah commented Dec 5, 2024 • edited Loading

What

Why

How

github-actions bot left a comment

Choose a reason for hiding this comment

lorenzsimon commented Dec 7, 2024

azizabah commented Dec 9, 2024

azizabah commented Dec 10, 2024

lorenzsimon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lorenzsimon commented Dec 15, 2024

lorenzsimon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

azizabah commented Dec 5, 2024 •

edited

Loading