docs: Add documentation for Schema annotation

Author: timonback

docs/documenting-producers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Documenting Producers

docs/documenting-schemas.md

@@ -0,0 +1,60 @@
+---
+sidebar_position: 4
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.md';
+import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.md';
+
+# Documenting Schemas
+
+Under the hood springwolf relies on swagger-core `ModelConverters`.
+
+By default, the type and example values for the properties are guessed.
+The default Jackson `ModelResolver` supports schema definitions via `@Schema` to overwrite the property definitions.
+
+## Using `@Schema`
+
+The `@Schema` annotation allows to set many properties like `description`, `example`, `required` to document payloads.
+
+All properties are part of the produced AsyncApi file. However, not all of them are displayed in springwolf-ui. The ones listed above are included.
+
+### Usage
+
+Add the following dependency:
+
+<Tabs>
+  <TabItem value="Groovy" label="Groovy" default>
+    <CodeBlock language="groovy">{CodeSchemaGroovy}</CodeBlock>
+  </TabItem>
+  <TabItem value="Maven" label="Maven">
+    <CodeBlock language="xml">{CodeSchemaMaven}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+Then, add the `@Schema` annotation to the payload class:
+```java
+import io.swagger.v3.oas.annotations.media.Schema;
+
+@Schema(description = "Example payload model")
+public class ExamplePayloadDto {
+    @Schema(description = "Some string field", example = "some string value", required = true)
+    private String someString;
+
+    public String getSomeString() {
+        return someString;
+    }
+}
+```
+
+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/stavshamir/springwolf/example/dtos/ExamplePayloadDto.java)
+
+## 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)

docs/manually-documenting-consumers.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 4
+sidebar_position: 5
 ---
 
 # Manually Documenting Consumers

docs/snippets/_schema_groovy.md

@@ -0,0 +1,3 @@
+dependencies {
+    implementation 'io.swagger.core.v3:swagger-core:2.2.0'
+}

docs/snippets/_schema_maven.md

@@ -0,0 +1,7 @@
+<dependencies>
+    <dependency>
+        <groupId>io.swagger.core.v3</groupId>
+        <artifactId>swagger-core</artifactId>
+        <version>2.2.0</version>
+    </dependency>
+</dependencies>

docs/supported-protocols.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 ---
 
 # Supported Protocols

package-lock.json

@@ -21,6 +21,7 @@
     "clsx": "^1.1.1",
     "file-loader": "^6.2.0",
     "prism-react-renderer": "^1.2.1",
+    "raw-loader": "^4.0.2",
     "react": "^17.0.1",
     "react-dom": "^17.0.1",
     "url-loader": "^4.1.1"