Skip to content

Commit 0bf9b08

Browse files
committed
docs: release 2.0.0
1 parent 2bcc4bb commit 0bf9b08

23 files changed

+4704
-3005
lines changed

docs/configuration/configuration.mdx

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -6,27 +6,31 @@ import CodeConfigurationProperties from '!!raw-loader!./snippets/_configuration_
66

77
# Configuration
88

9-
Add the following to the spring `application.properties` file:
9+
Starting in version 2.0.0, all properties are optional and have sensible defaults.
10+
11+
Selected configuration properties on short glance for the `application.properties` file:
1012
<CodeBlock language="properties">{CodeConfigurationProperties}</CodeBlock>
1113

12-
## Properties
14+
## Main Properties
15+
16+
### `base-backage`
1317

14-
### `base-backage` (required)
18+
The `base-package` is scanned for listeners and publishers.
19+
20+
In detail, Springwolf searches for `@Component` annotated classes (that includes `@Service` annotated classes) with methods annotated with `@AsyncListener`, `@AsyncPublisher`, `@JmsListener`, `@KafkaListener`, `@MessageMapping`, `@RabbitListener`, `@SqsListener`, etc.
21+
Also, `@Configuration` classes are scanned for `@Bean` classes containing the previously mentioned annotations.
1522

1623
It's recommended to structure the project such that all consumers and producers (classes containing listener/producer methods) are in the same package - it's not mandatory, and if they're scattered across multiple packages, just provide the highest in hierarchy package that contains all classes.
1724

1825
You can add multiple base packages separated by commas.
1926

20-
The `base-package` will be scanned for classes containing `@Component` annotated classes (that includes `@Service` annotated classes) for methods annotated with `@JmsListener`, `@KafkaListener`, `MessageMapping`, `@RabbitListener`, `@SqsListener`, `@AsyncListener`, `@AsyncPublisher`, etc.
21-
`@Configuration` classes are scanned for `@Bean` containing the previously mentioned annotations as well.
22-
23-
### `Info` (required)
27+
### `Info`
2428

2529
The `Info` object provides metadata about the API (see [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject)).
2630

2731
All provided fields will be present in the generated document, but not all will be displayed in the UI.
2832

29-
### `Servers` (required)
33+
### `Servers`
3034

3135
The `Server` object provides metadata to help the reader understand the protocol, version, login details and more (see [AsyncAPI Server Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#serversObject)).
3236
Any name (`kafka-server` in the example) can be chosen.
@@ -35,7 +39,7 @@ An AsyncAPI document can contain more than one server, but it's not common.
3539

3640
As with the `Info` object, all provided fields will be present in the generated document, but not all will be displayed in the UI.
3741

38-
## Additional `application.properties`
42+
## Additional Properties
3943

4044
The following table contains additional properties that can be specified in the `application.properties` file:
4145

@@ -81,7 +85,7 @@ The following table contains additional properties that can be specified in the
8185
The AsyncAPI specification allows the definition of additional data fields to extend the
8286
specification at certain points (see [Specification Extensions](https://www.asyncapi.com/docs/reference/specification/v3.0.0#specificationExtensions) ).
8387

84-
Extension Fields may be added to `Info`, `Contact`, `License` and `Server` objects both via `application.properties`.
88+
Extension Fields may be added to `Info`, `Contact`, `License` and `Server` objects in `application.properties`.
8589
Every custom extension field must begin with `x-`, for example `x-internal-id` (see sample configurations above).
8690

8791
## Grouping

docs/configuration/customizing.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ public class TagCustomizer implements OperationCustomizer {
6969

7070
The `DefaultAsyncApiSerializerService` is responsible for serializing the AsyncAPI document into a `String` for the Controller.
7171

72-
Use `DefaultAsyncApiSerializerService#getJsonObjectMapper()` and `DefaultAsyncApiSerializerService#getYamlObjectMapper()` to customize the `ObjectMapper`.
72+
Use `DefaultAsyncApiSerializerService#getJsonMapper()` and `DefaultAsyncApiSerializerService#getYamlMapper()` to customize the `ObjectMapper` (will change with migration to Jackson 3).
7373

7474
## `ChannelScanners` - Channel detection
7575

docs/configuration/documenting-consumers.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ Below is an example to demonstrate the annotation:
4141
))
4242
@KafkaAsyncOperationBinding
4343
public void receiveMessage(ExamplePayloadDto msg) {
44-
// process
44+
// do work
4545
}
4646
```
4747

docs/configuration/documenting-headers.mdx

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ public void receiveExamplePayload(
1616
@Payload ExamplePayloadDto payload, // @Payload is required for multiple parameters
1717
@Header(KafkaHeaders.RECEIVED_KEY) String key,
1818
@Header(KafkaHeaders.OFFSET) Integer offset) {
19-
// process
19+
// do work
2020
}
2121
```
2222

@@ -45,6 +45,6 @@ Again, the annotation property `headers` of `@AsyncOperation` allows to overwrit
4545
)
4646
))
4747
public void sendMessage(ExamplePayloadDto msg) {
48-
// process
48+
// do work
4949
}
5050
```

docs/configuration/documenting-messages.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ For example:
3333
)
3434
))
3535
public void sendMessage(ExamplePayloadDto msg) {
36-
// process
36+
// do work
3737
}
3838
```
3939

docs/configuration/documenting-producers.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Below is an example to demonstrate the annotation:
2828
))
2929
@KafkaAsyncOperationBinding
3030
public void sendMessage(ExamplePayloadDto msg) {
31-
// process
31+
// do work
3232
}
3333
```
3434

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,21 @@
1-
# Springwolf - required fields
1+
# Springwolf - optional, auto-detected fields
22
springwolf.docket.base-package=io.github.springwolf.example
33
springwolf.docket.info.title=${spring.application.name}
4-
springwolf.docket.info.version=1.0.0
5-
6-
springwolf.docket.servers.kafka-server.protocol=kafka
7-
springwolf.docket.servers.kafka-server.host=${spring.kafka.bootstrap-servers}
84

95
# Springwolf - optional fields
106
springwolf.enabled=true
117
springwolf.docket.default-content-type=application/json
12-
springwolf.docket.id=urn:io:github:springwolf:example
138
springwolf.docket.info.description=Springwolf example project to demonstrate springwolfs abilities
149
springwolf.docket.info.terms-of-service=http://asyncapi.org/terms
10+
springwolf.docket.info.version=1.0.0
1511
springwolf.docket.info.contact.name=springwolf
1612
springwolf.docket.info.contact.email=example@example.com
1713
springwolf.docket.info.contact.url=https://github.com/springwolf/springwolf-core
1814
springwolf.docket.info.license.name=Apache License 2.0
1915
springwolf.docket.info.x-internal-id=xyz-123
2016

17+
springwolf.docket.servers.kafka-server.protocol=kafka
18+
springwolf.docket.servers.kafka-server.host=${spring.kafka.bootstrap-servers}
19+
2120
# Springwolf - debugging
2221
logging.level.io.github.springwolf=DEBUG
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.32'
2+
implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.40'
33
}

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.32</version>
5+
<version>2.2.40</version>
66
</dependency>
77
</dependencies>

docs/faq.md

Lines changed: 50 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -29,12 +29,51 @@ See [Static Generation](static-generation.md).
2929
### Show `debug` output in the logs
3030

3131
Springwolf uses the default logging setup of Spring Boot.
32-
To enable `DEBUG` output, add the following line to the `application.properties`:
32+
To enable `DEBUG` output (`TRACE` for even more debugging), add the following line to the `application.properties`:
3333

3434
```properties
3535
logging.level.io.github.springwolf=DEBUG
3636
```
3737

38+
Log output:
39+
```log
40+
. ____ _ __ _ _
41+
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
42+
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
43+
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
44+
' |____| .__|_| |_|_| |_\__, | / / / /
45+
=========|_|==============|___/=/_/_/_/
46+
47+
:: Spring Boot :: (v4.0.2)
48+
49+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.examples.kafka.ApiIntegrationTest : Starting ApiIntegrationTest using Java 17.0.7 with PID 1792 (started by user in /springwolf-core/springwolf-examples/springwolf-kafka-example)
50+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.examples.kafka.ApiIntegrationTest : Running with Spring Boot v4.0.2, Spring v7.0.3
51+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.examples.kafka.ApiIntegrationTest : No active profile set, falling back to 1 default profile: "default"
52+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] o.s.boot.tomcat.TomcatWebServer : Tomcat initialized with port 0 (http)
53+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] o.apache.catalina.core.StandardService : Starting service [Tomcat]
54+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.15]
55+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] b.w.c.s.WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 522 ms
56+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.c.SpringwolfUiResourceConfigurer : Serving Springwolf with base-path: /springwolf
57+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.c.PublishingBaseController : Message publishing via SpringwolfKafkaController is active.
58+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] o.s.b.a.e.web.EndpointLinksResolver : Exposing 1 endpoint beneath base path '/actuator'
59+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] o.s.boot.tomcat.TomcatWebServer : Tomcat started on port 8080 (http) with context path '/'
60+
INFO 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.examples.kafka.ApiIntegrationTest : Started ApiIntegrationTest in 1.461 seconds (process running for 2.123)
61+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] .g.s.c.SpringwolfInitApplicationListener : Triggering asyncapi creation
62+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.asyncapi.DefaultAsyncApiService : Building AsyncAPI document
63+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.a.s.c.a.AnnotationScannerUtil : Detected method io.github.springwolf.examples.kafka.consumers.ExampleClassLevelKafkaListener#receiveMonetaryAmount
64+
...
65+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.a.s.c.a.AnnotationScannerUtil : Detected method io.github.springwolf.examples.kafka.consumers.AvroConsumer#receiveExampleAvroPayload
66+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.asyncapi.DefaultAsyncApiService : Starting customizer io.github.springwolf.addons.json_schema.JsonSchemaCustomizer
67+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.a.grouping.AsyncApiGroupService : Loaded AsyncApiGroup from configuration: AsyncApiGroup(groupName=Only Vehicles, groupInfo=Info(title=null, version=1.0.0, description=This group only contains endpoints that are related to vehicles., termsOfService=null, contact=null, license=null, tags=null, externalDocs=null), operationActionsToKeep=[], channelNamesToKeep=[], messageNamesToKeep=[.*Vehicle.*])
68+
DEBUG 1792 --- [Springwolf example project - Kafka] [ Test worker] i.g.s.c.asyncapi.DefaultAsyncApiService : AsyncAPI document was built
69+
INFO 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-1] o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
70+
INFO 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-1] o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet'
71+
INFO 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-1] o.s.web.servlet.DispatcherServlet : Completed initialization in 1 ms
72+
DEBUG 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-1] i.g.s.c.controller.AsyncApiController : Returning AsyncApi document for group Only Vehicles
73+
DEBUG 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-2] i.g.s.c.controller.AsyncApiController : Returning AsyncApi document for group default
74+
DEBUG 1792 --- [Springwolf example project - Kafka] [o-auto-1-exec-3] i.g.s.c.a.grouping.AsyncApiGroupService : Loaded AsyncApiGroup from configuration: AsyncApiGroup(groupName=Only Vehicles, groupInfo=Info(title=null, version=1.0.0, description=This group only contains endpoints that are related to vehicles., termsOfService=null, contact=null, license=null, tags=null, externalDocs=null), operationActionsToKeep=[], channelNamesToKeep=[], messageNamesToKeep=[.*Vehicle.*])
75+
```
76+
3877
### The Springwolf UI isn't showing
3978

4079
When the `springwolf-ui` dependency is added, the UI should be visible at [http://localhost:8080/springwolf/asyncapi-ui.html](http://localhost:8080/springwolf/asyncapi-ui.html).
@@ -62,7 +101,7 @@ If not, whether
62101
### Unable to publish message from the UI
63102

64103
Publishing messages from the UI is disabled by default due to security concerns.
65-
Springwolf doesn't offer authentication nor authorization, anyone can publish messages to (production) channels.
104+
Springwolf doesn't offer authentication nor authorization, anyone can publish messages to channels (in production).
66105
67106
Check the [configuration](configuration/configuration.mdx) to enable this feature.
68107
Be sure to enable fully qualified names ([`use-fqn`](configuration/configuration.mdx)) as well.
@@ -112,7 +151,7 @@ public void sendMessage(ListWrapper<String> msg) {}
112151
When Springwolf finds multiple consumers/producers for the same channel/topic, these are merged together.
113152
This is expected, as there are use-cases where different payloads are sent via the same channel/topic.
114153

115-
Springwolf uses on scanners to find all consumer and producers in your application.
154+
Springwolf uses scanners to find all consumer and producers in your application.
116155
Most likely two scanners found your consumer/producer each.
117156
See [configuration](configuration/configuration.mdx) to disable scanners.
118157

@@ -131,7 +170,14 @@ See the [customization page](configuration/customizing.md)
131170
Releases are managed in [GitHub Releases](https://github.com/springwolf/springwolf-core/releases),
132171
which feature noteworthy changes, the full changelog and notes on how to migrate.
133172

134-
Since each release has a git _tag_, the [Springwolf examples for each plugin](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples) showcase the use of Springwolf for any previous version.
173+
Since each release has a git [_tag_](https://github.com/springwolf/springwolf-core/tags),
174+
the [Springwolf examples](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples) showcase the use of Springwolf for any version.
175+
176+
### Is Spring Boot 3.X supported
177+
You can use an older version of Springwolf, which is build to support Spring Boot 3.X.
178+
However, these versions don't get any updates.
179+
180+
Last version to support Spring Boot 3.X is `1.20.0` as Spring Boot 4 started the Springwolf 2.X release line.
135181
136182
### How to migrate from Springwolf 0.18.0 to 1.0.0
137183

0 commit comments

Comments
 (0)