Skip to content

Commit 2d13a26

Browse files
timonbacktimonback
authored
docs: document usage of Schema annotation in Kotlin (#105)
1 parent 52b9a1e commit 2d13a26

File tree

6 files changed

+46
-30
lines changed

6 files changed

+46
-30
lines changed

‎docs/configuration/documenting-headers.mdx

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,6 @@
22
sidebar_position: 69
33
---
44

5-
import Tabs from '@theme/Tabs';
6-
import TabItem from '@theme/TabItem';
7-
import CodeBlock from '@theme/CodeBlock';
8-
import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle';
9-
import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml';
10-
115
# Headers
126

137
Springwolf provides different ways to document headers. The `header` is mapped to an AsyncAPI `schemaObject`.

‎docs/configuration/documenting-messages.mdx

Lines changed: 21 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@ sidebar_position: 68
55
import Tabs from '@theme/Tabs';
66
import TabItem from '@theme/TabItem';
77
import CodeBlock from '@theme/CodeBlock';
8-
import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle';
9-
import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml';
8+
import CodeSchemaDependencyGroovy from '!!raw-loader!./snippets/_schema_dependency_groovy.gradle';
9+
import CodeSchemaDependencyMaven from '!!raw-loader!./snippets/_schema_dependency_maven.xml';
10+
import CodeSchemaJava from '!!raw-loader!./snippets/_schema_java.java';
11+
import CodeSchemaKotlin from '!!raw-loader!./snippets/_schema_kotlin.kt';
1012

1113
# Messages
1214

@@ -75,47 +77,44 @@ The default Jackson `ModelResolver` supports schema definitions via `@Schema` to
7577
### Using `@Schema`
7678

7779
The `@Schema` annotation allows to set many properties like `description`, `example`, `requiredMode`, `minimum` to document payloads.
78-
79-
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))
80+
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,
81+
while the `@Schema` annotation contains some additional properties.
82+
Contribute in [#378](https://github.com/springwolf/springwolf-core/issues/378), so that all properties are supported in `springwolf-ui`.
8083

8184
#### Usage
8285

8386
Add the following dependency:
8487

8588
<Tabs>
8689
<TabItem value="Groovy" label="Groovy" default>
87-
<CodeBlock language="groovy">{CodeSchemaGroovy}</CodeBlock>
90+
<CodeBlock language="groovy">{CodeSchemaDependencyGroovy}</CodeBlock>
8891
</TabItem>
8992
<TabItem value="Maven" label="Maven">
90-
<CodeBlock language="xml">{CodeSchemaMaven}</CodeBlock>
93+
<CodeBlock language="xml">{CodeSchemaDependencyMaven}</CodeBlock>
9194
</TabItem>
9295
</Tabs>
9396

9497
Then, add the `@Schema` annotation to the payload class:
9598

96-
<!-- vale off -->
97-
```java
98-
import io.swagger.v3.oas.annotations.media.Schema;
99-
import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
100-
101-
@Schema(description = "Example payload model")
102-
public class ExamplePayloadDto {
103-
@Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
104-
private String someString;
105-
106-
public String getSomeString() {
107-
return someString;
108-
}
109-
}
110-
```
111-
<!-- vale on -->
99+
<Tabs>
100+
<TabItem value="Java" label="Java" default>
101+
<CodeBlock language="java">{CodeSchemaJava}</CodeBlock>
102+
</TabItem>
103+
<TabItem value="Kotlin" label="Kotlin">
104+
<CodeBlock language="kotlin">{CodeSchemaKotlin}</CodeBlock>
105+
</TabItem>
106+
</Tabs>
112107

113108
:::note
114109
The `@AsyncMessage.description` field will always override the `@Schema` description if provided
115110
:::
116111

117112
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)
118113

114+
#### Arrays using `@ArraySchema`
115+
116+
When the payload is an array, use `@ArraySchema` annotation instead.
117+
119118
#### Primitive, final and external classes
120119

121120
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 renamed to ‎docs/configuration/snippets/_schema_dependency_groovy.gradle

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
dependencies {
2-
implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.22'
2+
implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.32'
33
}

‎docs/configuration/snippets/_schema_maven.xml renamed to ‎docs/configuration/snippets/_schema_dependency_maven.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<dependency>
33
<groupId>io.swagger.core.v3</groupId>
44
<artifactId>swagger-core-jakarta</artifactId>
5-
<version>2.2.22</version>
5+
<version>2.2.32</version>
66
</dependency>
77
</dependencies>

‎docs/configuration/snippets/_schema_java.java

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import io.swagger.v3.oas.annotations.media.Schema;
2+
import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED;
3+
4+
@Schema(description = "Example payload model")
5+
public class ExamplePayloadDto {
6+
@Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
7+
private String someString;
8+
9+
public String getSomeString() {
10+
return someString;
11+
}
12+
}

‎docs/configuration/snippets/_schema_kotlin.kt

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
import io.swagger.v3.oas.annotations.media.Schema
2+
import io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED
3+
4+
@Schema(description = "Example payload model")
5+
public data class ExamplePayloadDto(
6+
// The `@field:` annotation use-site target is important
7+
@field:Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED)
8+
public val someString: String,
9+
)
10+
11+
// Note: Kotlin inline value classes use mangling: https://kotlinlang.org/docs/inline-classes.html#mangling

0 commit comments

Comments
 (0)