Skip to content

Commit 2aeb2a3

Browse files
stavshamirstavshamir
authored
Merge pull request #13 from timonback/feature/GH-12-document-schema-annotation
Document schema annotation
2 parents 64d5ab9 + 3ba98fc commit 2aeb2a3

11 files changed

+166
-30
lines changed

‎docs/documenting-producers.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

55
# Documenting Producers

‎docs/documenting-schemas.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
sidebar_position: 4
3+
---
4+
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.md';
9+
import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.md';
10+
11+
# Documenting Schemas
12+
13+
Under the hood springwolf relies on swagger-core `ModelConverters`.
14+
15+
By default, the type and example values for the properties are guessed.
16+
The default Jackson `ModelResolver` supports schema definitions via `@Schema` to overwrite the property definitions.
17+
18+
## Using `@Schema`
19+
20+
The `@Schema` annotation allows to set many properties like `description`, `example`, `required` to document payloads.
21+
22+
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.
23+
24+
### Usage
25+
26+
Add the following dependency:
27+
28+
<Tabs>
29+
<TabItem value="Groovy" label="Groovy" default>
30+
<CodeBlock language="groovy">{CodeSchemaGroovy}</CodeBlock>
31+
</TabItem>
32+
<TabItem value="Maven" label="Maven">
33+
<CodeBlock language="xml">{CodeSchemaMaven}</CodeBlock>
34+
</TabItem>
35+
</Tabs>
36+
37+
Then, add the `@Schema` annotation to the payload class:
38+
```java
39+
import io.swagger.v3.oas.annotations.media.Schema;
40+
41+
@Schema(description = "Example payload model")
42+
public class ExamplePayloadDto {
43+
@Schema(description = "Some string field", example = "some string value", required = true)
44+
private String someString;
45+
46+
public String getSomeString() {
47+
return someString;
48+
}
49+
}
50+
```
51+
52+
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)
53+
54+
## Custom ModelConverters
55+
56+
Additionally, custom `ModelConverters` are supported.
57+
These are needed when swagger is unable to extract a schema from a class.
58+
59+
One example is `javax.money.MonetaryAmount`.
60+
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‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 5
33
---
44

55
# Manually Documenting Consumers

‎docs/quickstart.md‎

Lines changed: 13 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
---
22
sidebar_position: 2
33
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
import CodeBlock from '@theme/CodeBlock';
7+
import CodeSpringwolfGroovy from '!!raw-loader!./snippets/_springwolf_groovy.md';
8+
import CodeSpringwolfMaven from '!!raw-loader!./snippets/_springwolf_maven.md';
49

510
# Quickstart
611

@@ -10,33 +15,14 @@ sidebar_position: 2
1015

1116
Add the following dependencies:
1217

13-
### [Groovy](#tab/groovy-dependencies)
14-
```groovy
15-
dependencies {
16-
// Provides the documentation API
17-
implementation 'io.github.springwolf:springwolf-kafka:0.8.0'
18-
19-
// Provides the UI - optional (recommended)
20-
runtimeOnly 'io.github.springwolf:springwolf-ui:0.5.0'
21-
}
22-
```
23-
### [Maven](#tab/maven-dependencies)
24-
```xml
25-
<dependencies>
26-
<!-- Provides the documentation API -->
27-
<dependency>
28-
<groupId>io.github.springwolf</groupId>
29-
<artifactId>springwolf-kafka</artifactId>
30-
<version>0.8.0</version>
31-
</dependency>
32-
<!-- Provides the UI - optional (recommended) -->
33-
<dependency>
34-
<groupId>io.github.springwolf</groupId>
35-
<artifactId>springwolf-ui</artifactId>
36-
<version>0.5.0</version>
37-
</dependency>
38-
</dependencies>
39-
```
18+
<Tabs>
19+
<TabItem value="Groovy" label="Groovy" default>
20+
<CodeBlock language="groovy">{CodeSpringwolfGroovy}</CodeBlock>
21+
</TabItem>
22+
<TabItem value="Maven" label="Maven">
23+
<CodeBlock language="xml">{CodeSpringwolfMaven}</CodeBlock>
24+
</TabItem>
25+
</Tabs>
4026

4127
## Configuration Class
4228

‎docs/snippets/_schema_groovy.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
dependencies {
2+
implementation 'io.swagger.core.v3:swagger-core:2.2.0'
3+
}

‎docs/snippets/_schema_maven.md‎

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.swagger.core.v3</groupId>
4+
<artifactId>swagger-core</artifactId>
5+
<version>2.2.0</version>
6+
</dependency>
7+
</dependencies>

‎docs/snippets/_springwolf_groovy.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
dependencies {
2+
// Provides the documentation API
3+
implementation 'io.github.springwolf:springwolf-kafka:0.8.0'
4+
5+
// Provides the UI - optional (recommended)
6+
runtimeOnly 'io.github.springwolf:springwolf-ui:0.5.0'
7+
}

‎docs/snippets/_springwolf_maven.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
<dependencies>
2+
<!-- Provides the documentation API -->
3+
<dependency>
4+
<groupId>io.github.springwolf</groupId>
5+
<artifactId>springwolf-kafka</artifactId>
6+
<version>0.8.0</version>
7+
</dependency>
8+
<!-- Provides the UI - optional (recommended) -->
9+
<dependency>
10+
<groupId>io.github.springwolf</groupId>
11+
<artifactId>springwolf-ui</artifactId>
12+
<version>0.5.0</version>
13+
</dependency>
14+
</dependencies>

‎docs/supported-protocols.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 6
33
---
44

55
# Supported Protocols

‎package-lock.json‎

Lines changed: 58 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)