Skip to content

Commit 52b9a1e

Browse files
timonbacktimonback
authored
docs: release 1.12.0 (#104)
* docs: prepare 1.12.0 release * docs: prepare 1.12.0 release * docs: prepare 1.12.0 release * docs: prepare 1.12.0 release
1 parent d859d95 commit 52b9a1e

17 files changed

+12535
-20428
lines changed

‎docs/configuration/documenting-bindings.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ You can define anything and there is no validation.
8080
```
8181

8282
:::info
83-
See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding) for more information
83+
See [Add-Ons / Generic Annotation Binding](../introduction/add-ons.mdx#generic-binding) for more information
8484
:::
8585

8686
## Binding properties

‎docs/configuration/documenting-messages.mdx

+1-1
Original file line numberDiff line numberDiff line change
@@ -137,5 +137,5 @@ static class StringEnvelope {
137137
```
138138

139139
:::info
140-
See [Add-Ons](../add-ons) for more information on how to document other formats
140+
See [Add-Ons](../introduction/add-ons) for more information on how to document other formats
141141
:::

‎docs/faq.md

+34-71
Original file line numberDiff line numberDiff line change
@@ -20,40 +20,9 @@ Either create a custom spring controller to serve the file or [serve static reso
2020

2121
Note: `springwolf-ui` doesn't support the full AsyncAPI spec.
2222

23-
### Unit test verification
23+
### Springwolf in unit / integration test
2424

25-
With the AsyncAPI artifact checked into the repository at `src/test/resources/asyncapi.json`,
26-
a unit test can verify that the current code still matches the expected AsyncAPI specification.
27-
Additionally, a diff reveals (un)expected changes.
28-
29-
Example unit test:
30-
31-
```java
32-
@SpringBootTest(
33-
classes = {SpringwolfKafkaExampleApplication.class},
34-
webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
35-
class ApiIntegrationTest {
36-
37-
@Autowired
38-
private TestRestTemplate restTemplate;
39-
40-
@Test
41-
void asyncApiResourceArtifactTest() throws IOException {
42-
String url = "/springwolf/docs";
43-
String actual = restTemplate.getForObject(url, String.class);
44-
45-
// writing the actual file can be useful for debugging (remember: gitignore)
46-
Files.writeString(Path.of("src", "test", "resources", "asyncapi.actual.json"), actual);
47-
48-
InputStream s = this.getClass().getResourceAsStream("/asyncapi.json");
49-
String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim();
50-
51-
assertEquals(expected, actual);
52-
}
53-
}
54-
```
55-
56-
For a full example, check the [springwolf-kafka-example ApiIntegrationTest](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/test/java/io/github/springwolf/examples/kafka/ApiIntegrationTest.java)
25+
See [Static Generation](static-generation.md).
5726

5827
## Troubleshooting
5928

@@ -100,18 +69,23 @@ Be sure to enable fully qualified names ([`use-fqn`](configuration/configuration
10069
10170
Spring Security allows to limit access to authorized users.
10271
103-
### Consumers are detected multiple times (with different payloads)
104-
105-
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
106-
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
72+
### Classes have fully qualified names (`io.springwolf.package.ClassName`)
10773
108-
Springwolf uses on scanners to find all consumer and producers in your application.
109-
Most likely two scanners found your consumer/producer each.
110-
See [configuration](configuration/configuration.mdx) to disable scanners.
74+
Disable the [fully qualified class name (FQN) option (`springwolf.use-fqn=false`)](configuration/configuration.mdx).
11175
11276
### Only one of multiple classes with the same name (different package) is detected
11377
114-
Enable the fully qualified class name (FQN) option (`springwolf.use-fqn=true`) so that Springwolf uses the FQN internally.
78+
Enable the [fully qualified class name (FQN) option (`springwolf.use-fqn=true`)](configuration/configuration.mdx).
79+
80+
### Springwolf interferes with OpenAPI documentation
81+
82+
Springwolf uses `swagger-core` to analyze classes, which is used by some OpenAPI libraries like `springdoc-openapi`.
83+
`swagger-core` configuration is partly global and can't be isolated.
84+
85+
Options:
86+
87+
1. Use the same settings in Springwolf and the other library (including the [fully qualified class name (FQN) option](configuration/configuration.mdx)).
88+
2. Don't run Springwolf and the other library at the same time, for example by [generating the documentation at build time](static-generation.md).
11589

11690
### Generic types (List) don't contain item properties
11791

@@ -133,6 +107,25 @@ class ListWrapper extends ArrayList<String> {}
133107
public void sendMessage(ListWrapper<String> msg) {}
134108
```
135109

110+
### Consumers are detected multiple times (with different payloads)
111+
112+
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
113+
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
114+
115+
Springwolf uses on scanners to find all consumer and producers in your application.
116+
Most likely two scanners found your consumer/producer each.
117+
See [configuration](configuration/configuration.mdx) to disable scanners.
118+
119+
## Usage Patterns
120+
121+
### How to access the generated documentation within java
122+
123+
Use the `AsyncApiService` to access the generated documentation.
124+
125+
### How to customize the generated documentation
126+
127+
See the [customization page](configuration/customizing.md)
128+
136129
## Release Notes / Migration Guide / Updating / Upgrading
137130

138131
Releases are managed in [GitHub Releases](https://github.com/springwolf/springwolf-core/releases),
@@ -160,33 +153,3 @@ Last versions to support Spring Boot 2.X:
160153
- `springwolf-core:0.6.0`
161154
- `springwolf-kafka:0.10.0`
162155
- `springwolf-ui:0.6.0`
163-
164-
## Usage Patterns
165-
166-
### How to access the generated documentation within java
167-
168-
Use the `AsyncApiService` to access the generated documentation.
169-
170-
### How to generate the documentation at build time
171-
172-
#### With Gradle
173-
174-
You can use the [`springdoc-openapi-gradle-plugin`](https://github.com/springdoc/springdoc-openapi-gradle-plugin) and configure the plugin
175-
for Springwolf by pointing it to the Springwolf docs endpoint:
176-
177-
```groovy
178-
openApi {
179-
apiDocsUrl = "http://localhost:8080/springwolf/docs"
180-
outputDir = file("$buildDir/docs")
181-
outputFileName = "async-api.json"
182-
}
183-
```
184-
185-
The [`springwolf-kafka-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/build.gradle)
186-
contains a working example.
187-
188-
The plugin will startup the spring boot application by using the `bootRun` task and then try to download the documentation
189-
from the given `apiDocsUrl` and store it in the `outputDir` and with the given `outputFileName`.
190-
191-
If your application is unable to start up with the `bootRun` task, see if [customBootRun](https://github.com/springdoc/springdoc-openapi-gradle-plugin#customization)
192-
properties can help you.

‎docs/add-ons.mdx renamed to ‎docs/introduction/add-ons.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 50
2+
sidebar_position: 20
33
---
44
import Tabs from '@theme/Tabs';
55
import TabItem from '@theme/TabItem';
@@ -49,7 +49,7 @@ Adding a model converter is demoed in [`springwolf-add-ons/springwolf-common-mod
4949
</Tabs>
5050
Latest version: ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-json-schema?color=green&label=springwolf&style=plastic)
5151

52-
Specific bindings are provided for the different [supported protocols](introduction/supported-protocols) but if you need
52+
Specific bindings are provided for the different [supported protocols](supported-protocols) but if you need
5353
to document a protocol that's not support yet, you can use this generic binding and specify any property you need.
5454

5555
### `@AsyncGenericOperationBinding`

‎docs/snippets/_springwolf_common_model_converters_groovy.gradle renamed to ‎docs/introduction/snippets/_springwolf_common_model_converters_groovy.gradle

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
dependencies {
2-
implementation 'io.github.springwolf:springwolf-common-model-converters:1.11.0'
2+
implementation 'io.github.springwolf:springwolf-common-model-converters:1.12.0'
33
}

‎docs/snippets/_springwolf_common_model_converters_maven.xml renamed to ‎docs/introduction/snippets/_springwolf_common_model_converters_maven.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<dependency>
33
<groupId>io.github.springwolf</groupId>
44
<artifactId>springwolf-common-model-converters</artifactId>
5-
<version>1.11.0</version>
5+
<version>1.12.0</version>
66
</dependency>
77
</dependencies>

‎docs/snippets/_springwolf_generic_binding_groovy.gradle renamed to ‎docs/introduction/snippets/_springwolf_generic_binding_groovy.gradle

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
dependencies {
2-
implementation 'io.github.springwolf:springwolf-generic-binding:1.11.0'
2+
implementation 'io.github.springwolf:springwolf-generic-binding:1.12.0'
33
}

‎docs/snippets/_springwolf_generic_binding_maven.xml renamed to ‎docs/introduction/snippets/_springwolf_generic_binding_maven.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<dependency>
33
<groupId>io.github.springwolf</groupId>
44
<artifactId>springwolf-generic-binding</artifactId>
5-
<version>1.11.0</version>
5+
<version>1.12.0</version>
66
</dependency>
77
</dependencies>

‎docs/snippets/_springwolf_json_schema_groovy.gradle renamed to ‎docs/introduction/snippets/_springwolf_json_schema_groovy.gradle

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
dependencies {
2-
implementation 'io.github.springwolf:springwolf-json-schema:1.11.0'
2+
implementation 'io.github.springwolf:springwolf-json-schema:1.12.0'
33
}

‎docs/snippets/_springwolf_json_schema_maven.xml renamed to ‎docs/introduction/snippets/_springwolf_json_schema_maven.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<dependency>
33
<groupId>io.github.springwolf</groupId>
44
<artifactId>springwolf-json-schema</artifactId>
5-
<version>1.11.0</version>
5+
<version>1.12.0</version>
66
</dependency>
77
</dependencies>

‎docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle renamed to ‎docs/introduction/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
dependencies {
2-
implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.11.0'
2+
implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.12.0'
33
}

‎docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml renamed to ‎docs/introduction/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
<dependency>
33
<groupId>io.github.springwolf</groupId>
44
<artifactId>springwolf-kotlinx-serialization-model-converter</artifactId>
5-
<version>1.11.0</version>
5+
<version>1.12.0</version>
66
</dependency>
77
</dependencies>

‎docs/introduction/supported-protocols.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ The supported binding annotations are:
4848
| STOMP (WebSocket) | `@StompAsyncOperationBinding` | ![Maven Central](https://img.shields.io/maven-central/v/io.github.springwolf/springwolf-stomp-binding?color=green&label=springwolf-stomp-binding&style=plastic) |
4949

5050
:::info
51-
See [Add-Ons / Generic Annotation Binding](../add-ons#generic-binding)
51+
See [Add-Ons / Generic Annotation Binding](add-ons.mdx#generic-binding)
5252
:::
5353

5454
## Wire format (Data serialization)
@@ -64,7 +64,7 @@ Besides the classical JSON events, Springwolf has best-effort support for some o
6464
[Protobuf](https://protobuf.dev) is demoed in [kafka example](#native-support).
6565

6666
To remove the fields generated by the Protobuf class generated, add a `ModelResolver` bean, which uses the `ProtobufModule` to your project.
67-
See [ObjectMapperConfiguration](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/springwolf/examples/kafka/configuration/ObjectMapperConfiguration.java) for details.
67+
See [ProtobufConfiguration](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/springwolf/examples/kafka/configuration/ProtobufConfiguration.java) for details.
6868

6969
[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
7070
[cloud-stream]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example

‎docs/snippets/_springwolf_groovy.gradle

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
dependencies {
22
// Provides the documentation API
3-
implementation 'io.github.springwolf:springwolf-kafka:1.11.0'
3+
implementation 'io.github.springwolf:springwolf-kafka:1.12.0'
44

55
// Provides the UI - optional (recommended)
6-
runtimeOnly 'io.github.springwolf:springwolf-ui:1.11.0'
6+
runtimeOnly 'io.github.springwolf:springwolf-ui:1.12.0'
77
}

‎docs/snippets/_springwolf_maven.xml

+2-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,12 @@
33
<dependency>
44
<groupId>io.github.springwolf</groupId>
55
<artifactId>springwolf-kafka</artifactId>
6-
<version>1.11.0</version>
6+
<version>1.12.0</version>
77
</dependency>
88
<!-- Provides the UI - optional (recommended) -->
99
<dependency>
1010
<groupId>io.github.springwolf</groupId>
1111
<artifactId>springwolf-ui</artifactId>
12-
<version>1.11.0</version>
12+
<version>1.12.0</version>
1313
</dependency>
1414
</dependencies>

‎docs/static-generation.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
sidebar_position: 40
3+
---
4+
5+
# Static Generation
6+
7+
Users tend to start out with running Springwolf at runtime as part of the Spring Boot application context.
8+
Still, it's possible to generate the AsyncAPI documentation statically at build time.
9+
10+
One use-case is to protect against unexpected API changes using a test.
11+
For this, the expected `asyncapi.json` file is stored in the VCS repository.
12+
13+
## Spring Boot Test (full spring context)
14+
15+
The most simple way is a Spring Boot test (taken from [springwolf-kafka-example](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/test/java/io/github/springwolf/examples/kafka/ApiIntegrationTest.java)):
16+
17+
```java
18+
@SpringBootTest(
19+
classes = {SpringwolfKafkaExampleApplication.class},
20+
webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
21+
class ApiIntegrationTest {
22+
23+
@Autowired
24+
private TestRestTemplate restTemplate;
25+
26+
@Test
27+
void asyncApiResourceArtifactTest() throws IOException {
28+
// given
29+
String url = "/springwolf/docs";
30+
31+
// when
32+
String actual = restTemplate.getForObject(url, String.class);
33+
34+
// then
35+
// writing the actual file can be useful for debugging (remember: .gitignore)
36+
Files.writeString(Path.of("src", "test", "resources", "asyncapi.actual.json"), actual);
37+
38+
// then
39+
InputStream s = this.getClass().getResourceAsStream("/asyncapi.json");
40+
String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim();
41+
assertEquals(expected, actual);
42+
}
43+
}
44+
```
45+
46+
## Springwolf Standalone (minimal spring context)
47+
48+
Especially for large application, starting the full Spring Boot context can be slow.
49+
Springwolf _standalone_ uses a minimal Spring application context, by only including beans and configurations marked with `@StandaloneConfiguration`.
50+
51+
Demo code (taken from [`springwolf-kafka-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/test/java/io/github/springwolf/examples/kafka/StandaloneTest.java)):
52+
53+
```java
54+
class StandaloneTest {
55+
56+
@Test
57+
public void asyncApiStandaloneArtifactTest() throws IOException {
58+
// given
59+
StandaloneApplication standaloneApplication =
60+
DefaultStandaloneApplication.builder().buildAndStart();
61+
62+
// when
63+
AsyncAPI asyncApi = standaloneApplication.getAsyncApiService().getAsyncAPI();
64+
String actual = new DefaultAsyncApiSerializerService().toJsonString(asyncApi);
65+
66+
// then
67+
// writing the actual file can be useful for debugging (remember: gitignore)
68+
Files.writeString(Path.of("src", "test", "resources", "asyncapi.standalone.json"), actual);
69+
70+
// then
71+
InputStream s = this.getClass().getResourceAsStream("/asyncapi.json");
72+
String expected = new String(s.readAllBytes(), StandardCharsets.UTF_8).trim();
73+
assertEquals(expected, actualPatched);
74+
}
75+
}
76+
```
77+
78+
By default, only the `io.github.springwolf` package is scanned and `@StandaloneConfiguration` in other packages are _not_ picked up.
79+
Use the `DefaultStandaloneApplication.builder()` to customize the Spring environment, load custom beans and configurations.
80+
81+
The [`application.properties` configuration](configuration/configuration.mdx) is picked up.
82+
83+
## Gradle Plugin (full spring context)
84+
85+
You can use the [`springdoc-openapi-gradle-plugin`](https://github.com/springdoc/springdoc-openapi-gradle-plugin) and configure the plugin
86+
for Springwolf (taken from [`springwolf-kafka-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/build.gradle)):
87+
88+
```groovy
89+
openApi {
90+
apiDocsUrl = "http://localhost:8080/springwolf/docs"
91+
outputDir = file("$buildDir/docs")
92+
outputFileName = "asyncapi.json"
93+
}
94+
```
95+
96+
The plugin will start up the spring boot application by using the `bootRun` task and then try to download the documentation
97+
from the given `apiDocsUrl` and store it in the `outputDir` and with the given `outputFileName`.
98+
99+
If your application is unable to start up with the `bootRun` task, see if [customBootRun](https://github.com/springdoc/springdoc-openapi-gradle-plugin#customization)
100+
properties can help you.

0 commit comments

Comments
 (0)