Skip to content

Commit a28ab73

Browse files
timonbacktimonback
committed
docs: Document application.properties springwolf configuration
1 parent 4568e3a commit a28ab73

File tree

4 files changed

+105
-74
lines changed

4 files changed

+105
-74
lines changed

‎docs/configuration.md‎

Lines changed: 34 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
---
22
sidebar_position: 3
33
---
4+
import Tabs from '@theme/Tabs';
5+
import TabItem from '@theme/TabItem';
6+
import CodeBlock from '@theme/CodeBlock';
7+
import CodeConfigurationProperties from '!!raw-loader!./snippets/_configuration_properties.md';
8+
import CodeConfigurationAsyncApiDocket from '!!raw-loader!./snippets/_configuration_asyncApiDocket.md';
49

510
# Configuration
611

7-
## Configuration Class
12+
## Activating
813

914
- You need to provide a configuration class annotated with:
1015
1. `@Configuration`
@@ -14,31 +19,32 @@ sidebar_position: 3
1419
```java
1520
@Configuration
1621
@EnableAsyncApi
17-
public class AsyncApiConfiguration {
18-
...
19-
}
22+
public class AsyncApiConfiguration { }
2023
```
2124

22-
## AsyncApiDocket
25+
## Springwolf configuration
2326

24-
You need to provide an `AsyncApiDocket` bean, which provides Springwolf with metadata that is either not specified in code or can't be picked up automatically.
27+
There are 2 ways to configure springwolf:
2528

26-
```java
27-
@Bean
28-
public AsyncApiDocket asyncApiDocket() {
29-
return AsyncApiDocket.builder()
30-
.basePackage(...)
31-
.info(...)
32-
.server(...)
33-
.build();
34-
}
35-
```
29+
1. `application.properties`, which is simple and should suit most use-cases
30+
2. `AsyncApiDocket`, which allows adding producers and consumers via code (and avoiding annotations)
31+
32+
<Tabs>
33+
<TabItem value="application.properties" label="application.properties" default>
34+
Add the following to the spring application.properties file.
35+
<CodeBlock language="properties">{CodeConfigurationProperties}</CodeBlock>
36+
</TabItem>
37+
<TabItem value="AsyncApiDocket" label="AsyncApiDocket">
38+
Add a AsyncApiDocket bean to the spring context, for example as part of the AsyncApiConfiguration.
39+
<CodeBlock language="java">{CodeConfigurationAsyncApiDocket}</CodeBlock>
40+
</TabItem>
41+
</Tabs>
3642

3743
### basePackage (required)
3844

39-
It is recommended to structue the project such that all consumers (classes containing listener methods) are in the same package - it is not mandatory, and if the consumer are scattered across multiple packages, just provide the highest in hierarchy package that containes all of them.
45+
It is recommended to structure the project such that all consumers and producers (classes containing listener/producer methods) are in the same package - it is not mandatory, and if they are scattered across multiple packages, just provide the highest in hierarchy package that contains all of them.
4046

41-
The base package will be scanned for classes containing `@Component` annotated classes (that includes `@Service` annotated classes) for methods annotated with `@KafkaListener`, `@RabbitListener`, etc.
47+
The base package will be scanned for classes containing `@Component` annotated classes (that includes `@Service` annotated classes) for methods annotated with `@KafkaListener`, `@RabbitListener`, `@AsyncSubscriber`, `@AsyncPublisher`, etc.
4248

4349
### Info (required)
4450

@@ -52,33 +58,18 @@ The `Server` object provides metadata the can help the reader understand the pro
5258

5359
An AsyncAPI document can contain more than one server, but it is not common.
5460

55-
The server is provided to the document with an arbitrary name as the key, and a `Server` object as the value:
56-
57-
```java
58-
@Bean
59-
public AsyncApiDocket asyncApiDocket() {
60-
Server kafkaServer = Server.builder()
61-
.protocol("kafka")
62-
.url(BOOTSTRAP_SERVERS)
63-
.build();
64-
65-
return AsyncApiDocket.builder()
66-
.basePackage(...)
67-
.info(...)
68-
.server("whatever name you want", kafkaServer)
69-
.build();
70-
}
71-
```
72-
7361
As with the `Info` object, all provided fields will be present in the generated document, but not all will be displayed in the UI.
7462

75-
## application.properties
63+
## Additional `application.properties`
7664

77-
The following table contains the complete list of additional properties that can be specified in the `application.properties` file:
65+
The following table contains additional properties that can be specified in the `application.properties` file:
7866

79-
| Property Name | Default Value | Description |
80-
| ------------- | ------------- | ----------- |
81-
| `springwolf.paths.docs` | `/springwolf/docs` | The path of the AsyncAPI document in JSON format. *Note that at the moment the UI will work only with the default value.* |
67+
| Property Name | Default Value | Description |
68+
|----------------------------------------------| ------------- |---------------------------------------------------------------------------------------------------------------------------|
69+
| `springwolf.enabled` | `true` | Allows to disable springwolf at one central place. |
70+
| `springwolf.paths.docs` | `/springwolf/docs` | The path of the AsyncAPI document in JSON format. *Note that at the moment the UI will work only with the default value.* |
71+
| `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce amqp messages from the UI. *Note that this has security implications* |
72+
| `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce kafka messages from the UI. *Note that this has security implications* |
8273

83-
[info]: https://www.asyncapi.com/docs/specifications/v2.0.0#infoObject).
84-
[server]: https://www.asyncapi.com/docs/specifications/v2.0.0#serverObject
74+
[info]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#infoObject.
75+
[server]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#serversObject

‎docs/quickstart.md‎

Lines changed: 22 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -26,45 +26,36 @@ Add the following dependencies:
2626

2727
## Configuration Class
2828

29-
Add the following configuration class.
30-
31-
*Make sure to change the value of `CONSUMERS_BASE_PACKAGE` to the package containing your Kafka listeners.*
29+
Add the following configuration class:
3230

3331
```java
3432
@Configuration
3533
@EnableAsyncApi
36-
public class AsyncApiConfiguration {
37-
38-
private final String BOOTSTRAP_SERVERS = "kafka:29092";
39-
private final String CONSUMERS_BASE_PACKAGE = "io.github.stavshamir.springwolf.example.consumers";
40-
41-
@Bean
42-
public AsyncApiDocket asyncApiDocket() {
43-
Info info = Info.builder()
44-
.version("1.0.0")
45-
.title("Springwolf example project")
46-
.build();
47-
48-
Server kafkaServer = Server.builder()
49-
.protocol("kafka")
50-
.url(BOOTSTRAP_SERVERS)
51-
.build();
52-
53-
return AsyncApiDocket.builder()
54-
.basePackage(CONSUMERS_BASE_PACKAGE)
55-
.info(info)
56-
.server("kafka", kafkaServer)
57-
.build();
58-
}
59-
60-
}
34+
public class AsyncApiConfiguration { }
6135
```
6236

37+
## Configuration properties
38+
39+
Add the following to your application.properties
40+
41+
```properties
42+
springwolf.docket.base-package=io.github.stavshamir.springwolf.example.consumers
43+
44+
springwolf.docket.info.title=${spring.application.name}
45+
springwolf.docket.info.version=1.0.0
46+
47+
springwolf.docket.servers.kafka.protocol=kafka
48+
springwolf.docket.servers.kafka.url=${kafka.bootstrap.servers:localhost:29092}
49+
```
50+
51+
*Make sure to change the value of `springwolf.docket.base-package` to the package containing your listeners.*
52+
6353
## View the docs
6454
After starting the application, visit `<host>:<port>/springwolf/asyncapi-ui.html` to view the UI or `<host>:<port>/springwolf/docs` to view the raw AsyncAPI document.
6555

6656
If you configured a different context path in your application, make sure to prepend it to springwolf urls, i.e. `<host>:<port>/<context-path>/springwolf/asyncapi-ui.html`
6757

68-
69-
[kafka]: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example
70-
[amqp]:https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
58+
## Examples
59+
- amqp: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-amqp-example
60+
- spring-cloud-stream: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-cloud-stream-example
61+
- kafka: https://github.com/springwolf/springwolf-core/tree/master/springwolf-examples/springwolf-kafka-example

‎docs/snippets/_configuration_asyncApiDocket.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
@Configuration
2+
@EnableAsyncApi
3+
public class AsyncApiConfiguration {
4+
5+
private final String BOOTSTRAP_SERVERS;
6+
7+
public AsyncApiConfiguration(@Value("${kafka.bootstrap.servers}") String bootstrapServers) {
8+
this.BOOTSTRAP_SERVERS = bootstrapServers;
9+
}
10+
11+
@Bean
12+
public AsyncApiDocket asyncApiDocket() {
13+
Info info = Info.builder()
14+
.title("Springwolf example project - Kafka")
15+
.version("1.0.0")
16+
.contact(Contact.builder()
17+
.name("springwolf")
18+
.url("https://github.com/springwolf/springwolf-core")
19+
.email("[email protected]")
20+
.build())
21+
.description("Springwolf example project to demonstrate springwolfs abilities")
22+
.license(License.builder()
23+
.name("Apache License 2.0")
24+
.build())
25+
.build();
26+
27+
return AsyncApiDocket.builder()
28+
.basePackage("io.github.stavshamir.springwolf.example.consumers")
29+
.info(info)
30+
.server("kafka", Server.builder()
31+
.protocol("kafka")
32+
.url(BOOTSTRAP_SERVERS)
33+
.build())
34+
.build();
35+
}
36+
}

‎docs/snippets/_configuration_properties.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
springwolf.docket.base-package=io.github.stavshamir.springwolf.example
2+
3+
springwolf.docket.info.title=${spring.application.name}
4+
springwolf.docket.info.version=1.0.0
5+
springwolf.docket.info.description=Springwolf example project to demonstrate springwolfs abilities
6+
springwolf.docket.info.terms-of-service=http://asyncapi.org/terms
7+
springwolf.docket.info.contact.name=springwolf
8+
springwolf.docket.info.contact.email=[email protected]
9+
springwolf.docket.info.contact.url=https://github.com/springwolf/springwolf-core
10+
springwolf.docket.info.license.name=Apache License 2.0
11+
12+
springwolf.docket.servers.kafka.protocol=kafka
13+
springwolf.docket.servers.kafka.url=${spring.kafka.bootstrap-servers}

0 commit comments

Comments
 (0)