From 3f411438684e59ce73e9cd636cd56f60da26ce94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?David=20M=C3=BCller?= Date: Fri, 26 Jul 2024 18:15:02 +0200 Subject: [PATCH 1/3] docs: document usage of operation customizer and replacing Springwolf beans with + custom implementations (#80) Co-authored-by: Timon Back --- .gitignore | 1 + docs/configuration/customizing.md | 41 ++++++++++++++++++++++++++++++- 2 files changed, 41 insertions(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index 91418e1..ce4c783 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,4 @@ node_modules .docusaurus build/** .idea +/*.iml diff --git a/docs/configuration/customizing.md b/docs/configuration/customizing.md index 17ebf30..ea269d0 100644 --- a/docs/configuration/customizing.md +++ b/docs/configuration/customizing.md @@ -23,7 +23,7 @@ All default implementations are Spring managed beans, which can be overridden. ## `AsyncApiCustomizer` - Full AsyncAPI document -By implementing the `AsyncApiCustomizer`, the AsyncAPI document can be modified after Springwolf has done all the scanning and has built the document. +By implementing the `AsyncApiCustomizer` interface, the AsyncAPI document can be modified after Springwolf has done all the scanning and has built the document. It's the final interception point before the document is available to the user. For example, the title can be adjusted - although this should be done through the configuration: @@ -38,6 +38,32 @@ public class AsyncApiTitleCustomizer implements AsyncApiCustomizer { } ``` +## `OperationCustomizer` - Operation object + +By implementing the `OperationCustomizer` interface, the Operation object can be modified after Springwolf has scanned an +annotated method and extracted the data. + +It is possible to create multiple implementations of `OperationCustomizer`. +The order of execution can be controlled by the `@Order` annotation of Spring. + +An example to conditionally add a custom AsyncAPI tag for Kafka batch listeners is shown bellow: + +```java +@Component +public class TagCustomizer implements OperationCustomizer { + + @Override + public void customize(Operation operation, Method method) { + KafkaListener annotation = AnnotationScannerUtil.findAnnotation(KafkaListener.class, method); + if (annotation != null && annotation.batch().equals("true")) { + Tag tag = new Tag(); + tag.setName("batch"); + operation.getTags().add(tag); + } + } +} +``` + ## ObjectMapper in `DefaultAsyncApiSerializerService` The `DefaultAsyncApiSerializerService` is responsible for serializing the AsyncAPI document into a `String` for the Controller. @@ -49,3 +75,16 @@ Use `DefaultAsyncApiSerializerService#getJsonObjectMapper()` and `DefaultAsyncAp All `ChannelScanner` beans are called to scan for channels. This interface is helpful when a protocol currently unsupported by Springwolf is used. Remember to register all payloads in the `ComponentsService`. + +## Customize internal behavior + +Springwolf uses `@ConditionalOnMissingBean` annotations for almost all internal Spring beans. +If you have a special use-case that requires custom logic, +you can replace almost every Springwolf bean by adding your custom implementation as a bean to the Spring context. + +:::note +Replacing Springwolf beans with custom implementations is only for experts, +and we do **not** offer support for using internal API. + +Custom implementations may break during updates without notice. +::: From 3372e0fbc8a52aa6b496b836efc58c94aca858c6 Mon Sep 17 00:00:00 2001 From: Timon Back Date: Sat, 27 Jul 2024 16:58:43 +0200 Subject: [PATCH 2/3] docs: linting --- docs/configuration/customizing.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuration/customizing.md b/docs/configuration/customizing.md index ea269d0..f77978d 100644 --- a/docs/configuration/customizing.md +++ b/docs/configuration/customizing.md @@ -43,7 +43,7 @@ public class AsyncApiTitleCustomizer implements AsyncApiCustomizer { By implementing the `OperationCustomizer` interface, the Operation object can be modified after Springwolf has scanned an annotated method and extracted the data. -It is possible to create multiple implementations of `OperationCustomizer`. +It's possible to create multiple implementations of `OperationCustomizer`. The order of execution can be controlled by the `@Order` annotation of Spring. An example to conditionally add a custom AsyncAPI tag for Kafka batch listeners is shown bellow: @@ -78,13 +78,13 @@ Remember to register all payloads in the `ComponentsService`. ## Customize internal behavior -Springwolf uses `@ConditionalOnMissingBean` annotations for almost all internal Spring beans. +Springwolf uses `@ConditionalOnMissingBean` annotations for most internal Spring beans. If you have a special use-case that requires custom logic, you can replace almost every Springwolf bean by adding your custom implementation as a bean to the Spring context. :::note -Replacing Springwolf beans with custom implementations is only for experts, -and we do **not** offer support for using internal API. +Replacing Springwolf beans with custom implementations is for experts only, +and **no** support is offered for using internal API. Custom implementations may break during updates without notice. ::: From f6321fc3a5ac685c5936f74e143b37508e28c5d0 Mon Sep 17 00:00:00 2001 From: Timon Back Date: Sat, 27 Jul 2024 17:07:33 +0200 Subject: [PATCH 3/3] docs: spelling & ordering --- docs/configuration/customizing.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/configuration/customizing.md b/docs/configuration/customizing.md index f77978d..9df7459 100644 --- a/docs/configuration/customizing.md +++ b/docs/configuration/customizing.md @@ -46,7 +46,7 @@ annotated method and extracted the data. It's possible to create multiple implementations of `OperationCustomizer`. The order of execution can be controlled by the `@Order` annotation of Spring. -An example to conditionally add a custom AsyncAPI tag for Kafka batch listeners is shown bellow: +An example to conditionally add a custom AsyncAPI `tag` for Kafka batch listeners is shown below: ```java @Component @@ -55,9 +55,10 @@ public class TagCustomizer implements OperationCustomizer { @Override public void customize(Operation operation, Method method) { KafkaListener annotation = AnnotationScannerUtil.findAnnotation(KafkaListener.class, method); - if (annotation != null && annotation.batch().equals("true")) { + if (annotation != null && "true".equals(annotation.batch())) { Tag tag = new Tag(); tag.setName("batch"); + operation.getTags().add(tag); } } @@ -78,13 +79,13 @@ Remember to register all payloads in the `ComponentsService`. ## Customize internal behavior -Springwolf uses `@ConditionalOnMissingBean` annotations for most internal Spring beans. -If you have a special use-case that requires custom logic, -you can replace almost every Springwolf bean by adding your custom implementation as a bean to the Spring context. - :::note -Replacing Springwolf beans with custom implementations is for experts only, -and **no** support is offered for using internal API. +Replacing Springwolf beans with custom implementations is for experts only. +**No** support is offered for using internal API. Custom implementations may break during updates without notice. ::: + +Springwolf uses `@ConditionalOnMissingBean` annotations for most internal Spring beans. +If you have a special use-case that requires custom logic, +you can replace almost every Springwolf bean by adding your custom implementation as a bean to the Spring context.