Skip to content

Commit eee8ef8

Browse files
ctasadactasada
authored
Merge pull request #78 from ctasada/ctasada/issue-77
(feat) Added add-ons documentation
2 parents ae70943 + e39eca1 commit eee8ef8

14 files changed

+186
-27
lines changed

‎.github/styles/config/vocabularies/Springwolf/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ APIs
88
Baeldung
99
declaratively
1010
Gradle
11+
Kotlinx
1112
Protobuf
1213
Springfox
1314
Springwolf

‎.vale.ini‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,7 @@ mdx = md
1111
BasedOnStyles = Vale, Microsoft
1212

1313
BlockIgnores = (import .*;)
14+
; Lets ignore Markdown links
15+
BlockIgnores = (?:\[(?P<text>.*?)\])\((?P<link>.*?)\)
1416

1517
Microsoft.Headings = NO

‎docs/add-ons.mdx‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
sidebar_position: 50
3+
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
import CodeBlock from '@theme/CodeBlock';
7+
import CodeCommonModelGroovy from '!!raw-loader!./snippets/_springwolf_common_model_converters_groovy.gradle';
8+
import CodeCommonModelMaven from '!!raw-loader!./snippets/_springwolf_common_model_converters_maven.xml';
9+
import CodeJsonSchemaGroovy from '!!raw-loader!./snippets/_springwolf_json_schema_groovy.gradle';
10+
import CodeJsonSchemaMaven from '!!raw-loader!./snippets/_springwolf_json_schema_maven.xml';
11+
import CodeGenericBindingGroovy from '!!raw-loader!./snippets/_springwolf_generic_binding_groovy.gradle';
12+
import CodeGenericBindingMaven from '!!raw-loader!./snippets/_springwolf_generic_binding_maven.xml';
13+
import CodeKotlinxGroovy from '!!raw-loader!./snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle';
14+
import CodeKotlinxMaven from '!!raw-loader!./snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml';
15+
16+
# Add-Ons
17+
18+
## Common Model Converters
19+
20+
The [`springwolf-add-ons/springwolf-common-model-converters`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-common-model-converters) adds support for different Model Converters.
21+
22+
These are needed when swagger is unable to extract a schema from a class.
23+
24+
Add the following dependency:
25+
26+
<Tabs>
27+
<TabItem value="Groovy" label="Groovy" default>
28+
<CodeBlock language="groovy">{CodeCommonModelGroovy}</CodeBlock>
29+
</TabItem>
30+
<TabItem value="Maven" label="Maven">
31+
<CodeBlock language="xml">{CodeCommonModelMaven}</CodeBlock>
32+
</TabItem>
33+
</Tabs>
34+
Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-common-model-converters?color=green&label=springwolf&style=plastic)
35+
36+
### `javax.money.MonetaryAmount`
37+
38+
Adding a model converter is demoed in [`springwolf-add-ons/springwolf-common-model-converters`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-common-model-converters)
39+
40+
## Generic Binding
41+
42+
<Tabs>
43+
<TabItem value="Groovy" label="Groovy" default>
44+
<CodeBlock language="groovy">{CodeGenericBindingGroovy}</CodeBlock>
45+
</TabItem>
46+
<TabItem value="Maven" label="Maven">
47+
<CodeBlock language="xml">{CodeGenericBindingMaven}</CodeBlock>
48+
</TabItem>
49+
</Tabs>
50+
Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-json-schema?color=green&label=springwolf&style=plastic)
51+
52+
Specific bindings are provided for the different [supported protocols](introduction/supported-protocols) but if you need
53+
to document a protocol that's not support yet, you can use this generic binding and specify any property you need.
54+
55+
### `@AsyncGenericOperationBinding`
56+
57+
The annotation parameter `type` is expected to contain the id of a valid [operation binding protocol](https://www.asyncapi.com/docs/reference/specification/v3.0.0#operationBindingsObject)
58+
but no validation is done.
59+
60+
The annotation parameter `fields` is intended to contain the fields that describe the protocol fields.
61+
62+
* **Key-Value**: A simple field can be described like `{"key-name=value"}`
63+
* **Array**: An array structure can be defined like `{"key=[valueA, valueB, valueC]"}`
64+
* **Map**: A map can be defined as `{"nested.keyA=value", "nested.keyB=value", "nested.keyC.subvalue=value"}`
65+
66+
You can define anything and there is **no validation**.
67+
68+
```java
69+
@AsyncGenericOperationBinding(
70+
type = "custom-binding",
71+
fields = {
72+
"internal-field=customValue",
73+
"nested.key=nestedValue",
74+
"listKey=[a,b,c,d,e]"
75+
}
76+
)
77+
```
78+
79+
## Json-Schema
80+
81+
The [`springwolf-add-ons/springwolf-json-schema`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-json-schema) adds the [json-schema](https://json-schema.org) schema to the AsyncAPI document.
82+
83+
Add the following dependency:
84+
85+
<Tabs>
86+
<TabItem value="Groovy" label="Groovy" default>
87+
<CodeBlock language="groovy">{CodeJsonSchemaGroovy}</CodeBlock>
88+
</TabItem>
89+
<TabItem value="Maven" label="Maven">
90+
<CodeBlock language="xml">{CodeJsonSchemaMaven}</CodeBlock>
91+
</TabItem>
92+
</Tabs>
93+
Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-json-schema?color=green&label=springwolf&style=plastic)
94+
95+
## Kotlinx Serialization
96+
97+
:::caution
98+
This add-on is still **Beta** so some features may not be yet implemented or some issues may be
99+
expected. Please, fill a [SpringWold Issue](https://github.com/springwolf/springwolf.github.io/issues/new) if you find
100+
any bug or a missing feature.
101+
:::
102+
103+
To support [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization) classes, add the following dependency:
104+
105+
<Tabs>
106+
<TabItem value="Groovy" label="Groovy" default>
107+
<CodeBlock language="groovy">{CodeKotlinxGroovy}</CodeBlock>
108+
</TabItem>
109+
<TabItem value="Maven" label="Maven">
110+
<CodeBlock language="xml">{CodeKotlinxMaven}</CodeBlock>
111+
</TabItem>
112+
</Tabs>
113+
Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-kotlinx-serialization-model-converter?color=green&label=springwolf&style=plastic)
114+
115+
Using this add-on, any Kotlin class annotated with the `@Serializable` annotation is _properly_ converted to AsyncAPI specification.
116+
117+
The fields annotated with `@SerialName` are named as defined in the annotation.
118+
119+
**Known issues:**
120+
121+
* Polymorphism is still **not** supported. See [issue #707](https://github.com/springwolf/springwolf-core/issues/707)

‎docs/configuration/documenting-bindings.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,10 @@ You can define anything and there is no validation.
7171
)
7272
```
7373

74+
:::info
75+
See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding) for more information
76+
:::
77+
7478
## Binding properties
7579

7680
Explanation of the different binding properties.

‎docs/configuration/documenting-messages.mdx‎

Lines changed: 3 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -135,14 +135,6 @@ static class StringEnvelope {
135135
}
136136
```
137137

138-
### `json-schema`
139-
140-
The [`springwolf-add-ons/springwolf-json-schema`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-json-schema) adds the [json-schema](https://json-schema.org) schema to the AsyncAPI document.
141-
142-
## Custom ModelConverters
143-
144-
Additionally, custom `ModelConverters` are supported.
145-
These are needed when swagger is unable to extract a schema from a class.
146-
147-
One example is `javax.money.MonetaryAmount`.
148-
Adding a model converter is demoed in [`springwolf-add-ons/springwolf-common-model-converters`](https://github.com/springwolf/springwolf-core/tree/master/springwolf-add-ons/springwolf-common-model-converters)
138+
:::info
139+
See [Add-Ons](../add-ons) for more information on how to document other formats
140+
:::

‎docs/introduction/supported-protocols.md‎

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,21 @@ Using [`@AsyncListener`](../configuration/documenting-consumers.md) and [`@Async
3131

3232
The protocols with native support come along with a `@_ProtocolName_Binding` annotation to define protocol specific properties.
3333

34-
### `springwolf-generic-binding` add-on
35-
36-
The `springwolf-generic-binding` add-on allows to document any binding.
37-
This includes bindings not supported by Springwolf, but also any custom fields not part of the AsyncAPI specification.
38-
39-
```java
40-
@AsyncPublisher(...)
41-
@AsyncGenericOperationBinding(
42-
type = "custom-protocol-binding",
43-
fields = {
44-
"internal-field=customValue",
45-
"nested.key=nestedValue"})
46-
public void sendMessage(AnotherPayloadDto msg) {
47-
// publish message
48-
}
49-
```
34+
### `springwolf-<protocol>-binding` bindings
35+
36+
Springwolf also provides some libraries to document bindings. Those libraries provide a light alternative (without 3rd party dependencies)
37+
38+
The supported binding annotations are:
39+
40+
| Protocol | Annotations | Latest Plugin Version |
41+
|---------------|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
42+
| GooglePubSub | `@GooglePubSubAsyncChannelBinding` | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-googlepubsub-binding?color=green&label=springwolf-googlepubsub-binding&style=plastic) |
43+
| SNS | `@SnsAsyncOperationBinding` | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sns-binding?color=green&label=springwolf-sns-binding&style=plastic) |
44+
| SQS | `@SqsAsyncOperationBinding` | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-sqs-binding?color=green&label=springwolf-sqs-binding&style=plastic) |
45+
46+
:::info
47+
See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding)
48+
:::
5049

5150
[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
5251
[cloud-stream]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example

‎docs/snippets/_springwolf_common_model_converters_groovy.gradle‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
dependencies {
2+
implementation 'io.github.springwolf:springwolf-common-model-converters:1.1.0'
3+
}

‎docs/snippets/_springwolf_common_model_converters_maven.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<dependencies>
2+
<dependency>
3+
<groupId>io.github.springwolf</groupId>
4+
<artifactId>springwolf-common-model-converters</artifactId>
5+
<version>1.1.0</version>
6+
</dependency>
7+
</dependencies>

‎docs/snippets/_springwolf_generic_binding_groovy.gradle‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
dependencies {
2+
implementation 'io.github.springwolf:springwolf-generic-binding:1.1.0'
3+
}

‎docs/snippets/_springwolf_generic_binding_maven.xml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
<dependencies>
2+
<dependency>
3+
<groupId>io.github.springwolf</groupId>
4+
<artifactId>springwolf-generic-binding</artifactId>
5+
<version>1.1.0</version>
6+
</dependency>
7+
</dependencies>

0 commit comments

Comments
 (0)