docs: document usage of Schema annotation in Kotlin

docs/configuration/documenting-headers.mdx

@@ -2,12 +2,6 @@
 sidebar_position: 69
 ---
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-import CodeBlock from '@theme/CodeBlock';
-import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle';
-import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml';
-
 # Headers
 
 Springwolf provides different ways to document headers. The `header` is mapped to an AsyncAPI `schemaObject`.

docs/configuration/documenting-messages.mdx

@@ -5,8 +5,10 @@ sidebar_position: 68
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import CodeBlock from '@theme/CodeBlock';
-import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle';
-import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml';
+import CodeSchemaDependencyGroovy from '!!raw-loader!./snippets/_schema_dependency_groovy.gradle';
+import CodeSchemaDependencyMaven from '!!raw-loader!./snippets/_schema_dependency_maven.xml';
+import CodeSchemaJava from '!!raw-loader!./snippets/_schema_java.java';
+import CodeSchemaKotlin from '!!raw-loader!./snippets/_schema_kotlin.kt';
 
 # Messages
 
@@ -75,47 +77,44 @@ The default Jackson `ModelResolver` supports schema definitions via `@Schema` to
 ### Using `@Schema`
 
 The `@Schema` annotation allows to set many properties like `description`, `example`, `requiredMode`, `minimum` to document payloads.
-
-All properties are part of the produced AsyncAPI file. However, not all are displayed in `springwolf-ui` (see [#378](https://github.com/springwolf/springwolf-core/issues/378))
+Only properties that are part of [AsyncAPI spec](https://www.asyncapi.com/docs/reference/specification/v3.0.0#schemaObject) are part of the produced AsyncAPI file,
+while the `@Schema` annotation contains some additional properties.
+Contribute in [#378](https://github.com/springwolf/springwolf-core/issues/378), so that all properties are supported in `springwolf-ui`.
 
 #### Usage
 
 Add the following dependency:
 
 <Tabs>
   <TabItem value="Groovy" label="Groovy" default>
-    <CodeBlock language="groovy">{CodeSchemaGroovy}</CodeBlock>
+    <CodeBlock language="groovy">{CodeSchemaDependencyGroovy}</CodeBlock>
   </TabItem>
   <TabItem value="Maven" label="Maven">
-    <CodeBlock language="xml">{CodeSchemaMaven}</CodeBlock>
+    <CodeBlock language="xml">{CodeSchemaDependencyMaven}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Then, add the `@Schema` annotation to the payload class:
 
-<!-- vale off -->
-```java
-import io.swagger.v3.oas.annotations.media.Schema;
-import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
-
-@Schema(description = "Example payload model")
-public class ExamplePayloadDto {
-    @Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
-    private String someString;
-
-    public String getSomeString() {
-        return someString;
-    }
-}
-```
-<!-- vale on -->
+<Tabs>
+  <TabItem value="Java" label="Java" default>
+    <CodeBlock language="java">{CodeSchemaJava}</CodeBlock>
+  </TabItem>
+  <TabItem value="Kotlin" label="Kotlin">
+    <CodeBlock language="kotlin">{CodeSchemaKotlin}</CodeBlock>
+  </TabItem>
+</Tabs>
 
 :::note
 The `@AsyncMessage.description` field will always override the `@Schema` description if provided
 :::
 
 For a full example, take a look at [ExamplePayloadDto.java in `springwolf-amqp-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/springwolf/examples/amqp/dtos/ExamplePayloadDto.java)
 
+#### Arrays using `@ArraySchema`
+
+When the payload is an array, use `@ArraySchema` annotation instead.
+
 #### Primitive, final and external classes
 
 When the `@Schema` annotation can't be attached to the payload class (that's `java.lang.String`), the payload can be wrapped in an envelope class. The actual payload is a field within this class (`StringEnvelope`), marked using `@AsyncApiPayload` and documented using the `@Schema` annotation.

docs/configuration/snippets/_schema_groovy.gradle → docs/configuration/snippets/_schema_dependency_groovy.gradle

@@ -1,3 +1,3 @@
 dependencies {
-    implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.22'
+    implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.32'
 }

docs/configuration/snippets/_schema_maven.xml → docs/configuration/snippets/_schema_dependency_maven.xml

@@ -2,6 +2,6 @@
     <dependency>
         <groupId>io.swagger.core.v3</groupId>
         <artifactId>swagger-core-jakarta</artifactId>
-        <version>2.2.22</version>
+        <version>2.2.32</version>
     </dependency>
 </dependencies>

docs/configuration/snippets/_schema_java.java

@@ -0,0 +1,12 @@
+import io.swagger.v3.oas.annotations.media.Schema;
+import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
+
+@Schema(description = "Example payload model")
+public class ExamplePayloadDto {
+    @Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
+    private String someString;
+
+    public String getSomeString() {
+        return someString;
+    }
+}

docs/configuration/snippets/_schema_kotlin.kt

@@ -0,0 +1,11 @@
+import io.swagger.v3.oas.annotations.media.Schema
+import io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED
+
+@Schema(description = "Example payload model")
+public data class ExamplePayloadDto(
+    // The `@field:` annotation use-site target is important
+    @field:Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
+    public val someString: String,
+)
+
+// Note: Kotlin inline value classes use mangling: https://kotlinlang.org/docs/inline-classes.html#mangling