From 282a7c0b198d7de8a2e4b9a379355a5a26758a36 Mon Sep 17 00:00:00 2001 From: Carlos Tasada Date: Sat, 20 Apr 2024 13:07:49 +0200 Subject: [PATCH] (feat) Added add-ons documentation Fixes #77. This MR adds documentation about the add-ons, including the new Kotlinx add-on. --- .../config/vocabularies/Springwolf/accept.txt | 1 + .vale.ini | 2 + docs/add-ons.mdx | 121 ++++++++++++++++++ docs/configuration/documenting-bindings.md | 4 + docs/configuration/documenting-messages.mdx | 14 +- ...wolf_common_model_converters_groovy.gradle | 3 + ...ringwolf_common_model_converters_maven.xml | 7 + .../_springwolf_generic_binding_groovy.gradle | 3 + .../_springwolf_generic_binding_maven.xml | 7 + .../_springwolf_json_schema_groovy.gradle | 3 + .../_springwolf_json_schema_maven.xml | 7 + ...erialization_model_converter_groovy.gradle | 3 + ...nx_serialization_model_converter_maven.xml | 7 + 13 files changed, 171 insertions(+), 11 deletions(-) create mode 100644 docs/add-ons.mdx create mode 100644 docs/snippets/_springwolf_common_model_converters_groovy.gradle create mode 100644 docs/snippets/_springwolf_common_model_converters_maven.xml create mode 100644 docs/snippets/_springwolf_generic_binding_groovy.gradle create mode 100644 docs/snippets/_springwolf_generic_binding_maven.xml create mode 100644 docs/snippets/_springwolf_json_schema_groovy.gradle create mode 100644 docs/snippets/_springwolf_json_schema_maven.xml create mode 100644 docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle create mode 100644 docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml diff --git a/.github/styles/config/vocabularies/Springwolf/accept.txt b/.github/styles/config/vocabularies/Springwolf/accept.txt index c86976f..d4286bc 100644 --- a/.github/styles/config/vocabularies/Springwolf/accept.txt +++ b/.github/styles/config/vocabularies/Springwolf/accept.txt @@ -8,6 +8,7 @@ APIs Baeldung declaratively Gradle +Kotlinx Protobuf Springfox Springwolf diff --git a/.vale.ini b/.vale.ini index 0e37d6e..d66319f 100644 --- a/.vale.ini +++ b/.vale.ini @@ -11,5 +11,7 @@ mdx = md BasedOnStyles = Vale, Microsoft BlockIgnores = (import .*;) +; Lets ignore Markdown links +BlockIgnores = (?:\[(?P.*?)\])\((?P.*?)\) Microsoft.Headings = NO diff --git a/docs/add-ons.mdx b/docs/add-ons.mdx new file mode 100644 index 0000000..64bcc23 --- /dev/null +++ b/docs/add-ons.mdx @@ -0,0 +1,121 @@ +--- +sidebar_position: 50 +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; +import CodeCommonModelGroovy from '!!raw-loader!./snippets/_springwolf_common_model_converters_groovy.gradle'; +import CodeCommonModelMaven from '!!raw-loader!./snippets/_springwolf_common_model_converters_maven.xml'; +import CodeJsonSchemaGroovy from '!!raw-loader!./snippets/_springwolf_json_schema_groovy.gradle'; +import CodeJsonSchemaMaven from '!!raw-loader!./snippets/_springwolf_json_schema_maven.xml'; +import CodeGenericBindingGroovy from '!!raw-loader!./snippets/_springwolf_generic_binding_groovy.gradle'; +import CodeGenericBindingMaven from '!!raw-loader!./snippets/_springwolf_generic_binding_maven.xml'; +import CodeKotlinxGroovy from '!!raw-loader!./snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle'; +import CodeKotlinxMaven from '!!raw-loader!./snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml'; + +# Add-Ons + +## Common Model Converters + +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. + +These are needed when swagger is unable to extract a schema from a class. + +Add the following dependency: + + + + {CodeCommonModelGroovy} + + + {CodeCommonModelMaven} + + +Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-common-model-converters?color=green&label=springwolf&style=plastic) + +### `javax.money.MonetaryAmount` + +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) + +## Generic Binding + + + + {CodeGenericBindingGroovy} + + + {CodeGenericBindingMaven} + + +Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-json-schema?color=green&label=springwolf&style=plastic) + +Specific bindings are provided for the different [supported protocols](introduction/supported-protocols) but if you need +to document a protocol that's not support yet, you can use this generic binding and specify any property you need. + +### `@AsyncGenericOperationBinding` + +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) +but no validation is done. + +The annotation parameter `fields` is intended to contain the fields that describe the protocol fields. + +* **Key-Value**: A simple field can be described like `{"key-name=value"}` +* **Array**: An array structure can be defined like `{"key=[valueA, valueB, valueC]"}` +* **Map**: A map can be defined as `{"nested.keyA=value", "nested.keyB=value", "nested.keyC.subvalue=value"}` + +You can define anything and there is **no validation**. + +```java +@AsyncGenericOperationBinding( + type = "custom-binding", + fields = { + "internal-field=customValue", + "nested.key=nestedValue", + "listKey=[a,b,c,d,e]" + } +) +``` + +## Json-Schema + +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. + +Add the following dependency: + + + + {CodeJsonSchemaGroovy} + + + {CodeJsonSchemaMaven} + + +Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-json-schema?color=green&label=springwolf&style=plastic) + +## Kotlinx Serialization + +:::caution +This add-on is still **Beta** so some features may not be yet implemented or some issues may be +expected. Please, fill a [SpringWold Issue](https://github.com/springwolf/springwolf.github.io/issues/new) if you find +any bug or a missing feature. +::: + +To support [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization) classes, add the following dependency: + + + + {CodeKotlinxGroovy} + + + {CodeKotlinxMaven} + + +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) + +Using this add-on, any Kotlin class annotated with the `@Serializable` annotation is _properly_ converted to AsyncAPI specification. + +The fields annotated with `@SerialName` are named as defined in the annotation. + +**Known issues:** + +* Polymorphism is still **not** supported. See [issue #707](https://github.com/springwolf/springwolf-core/issues/707) diff --git a/docs/configuration/documenting-bindings.md b/docs/configuration/documenting-bindings.md index fb6a736..78a54e0 100644 --- a/docs/configuration/documenting-bindings.md +++ b/docs/configuration/documenting-bindings.md @@ -71,6 +71,10 @@ You can define anything and there is no validation. ) ``` +:::info +See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding) for more information +::: + ## Binding properties Explanation of the different binding properties. diff --git a/docs/configuration/documenting-messages.mdx b/docs/configuration/documenting-messages.mdx index 9298c55..7ecade4 100644 --- a/docs/configuration/documenting-messages.mdx +++ b/docs/configuration/documenting-messages.mdx @@ -135,14 +135,6 @@ static class StringEnvelope { } ``` -### `json-schema` - -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. - -## Custom ModelConverters - -Additionally, custom `ModelConverters` are supported. -These are needed when swagger is unable to extract a schema from a class. - -One example is `javax.money.MonetaryAmount`. -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) +:::info +See [Add-Ons](../add-ons.md) for more information on how to document other formats +::: diff --git a/docs/snippets/_springwolf_common_model_converters_groovy.gradle b/docs/snippets/_springwolf_common_model_converters_groovy.gradle new file mode 100644 index 0000000..da73619 --- /dev/null +++ b/docs/snippets/_springwolf_common_model_converters_groovy.gradle @@ -0,0 +1,3 @@ +dependencies { + implementation 'io.github.springwolf:springwolf-common-model-converters:1.1.0' +} diff --git a/docs/snippets/_springwolf_common_model_converters_maven.xml b/docs/snippets/_springwolf_common_model_converters_maven.xml new file mode 100644 index 0000000..209e060 --- /dev/null +++ b/docs/snippets/_springwolf_common_model_converters_maven.xml @@ -0,0 +1,7 @@ + + + io.github.springwolf + springwolf-common-model-converters + 1.1.0 + + diff --git a/docs/snippets/_springwolf_generic_binding_groovy.gradle b/docs/snippets/_springwolf_generic_binding_groovy.gradle new file mode 100644 index 0000000..3d9c03c --- /dev/null +++ b/docs/snippets/_springwolf_generic_binding_groovy.gradle @@ -0,0 +1,3 @@ +dependencies { + implementation 'io.github.springwolf:springwolf-generic-binding:1.1.0' +} diff --git a/docs/snippets/_springwolf_generic_binding_maven.xml b/docs/snippets/_springwolf_generic_binding_maven.xml new file mode 100644 index 0000000..a289081 --- /dev/null +++ b/docs/snippets/_springwolf_generic_binding_maven.xml @@ -0,0 +1,7 @@ + + + io.github.springwolf + springwolf-generic-binding + 1.1.0 + + diff --git a/docs/snippets/_springwolf_json_schema_groovy.gradle b/docs/snippets/_springwolf_json_schema_groovy.gradle new file mode 100644 index 0000000..6cb66e9 --- /dev/null +++ b/docs/snippets/_springwolf_json_schema_groovy.gradle @@ -0,0 +1,3 @@ +dependencies { + implementation 'io.github.springwolf:springwolf-json-schema:1.1.0' +} diff --git a/docs/snippets/_springwolf_json_schema_maven.xml b/docs/snippets/_springwolf_json_schema_maven.xml new file mode 100644 index 0000000..aabde3d --- /dev/null +++ b/docs/snippets/_springwolf_json_schema_maven.xml @@ -0,0 +1,7 @@ + + + io.github.springwolf + springwolf-json-schema + 1.1.0 + + diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle new file mode 100644 index 0000000..cc237cb --- /dev/null +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle @@ -0,0 +1,3 @@ +dependencies { + implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.1.0' +} diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml new file mode 100644 index 0000000..862461c --- /dev/null +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml @@ -0,0 +1,7 @@ + + + io.github.springwolf + springwolf-kotlinx-serialization-model-converter + 1.1.0 + +