diff --git a/docs/configuration/configuration.mdx b/docs/configuration/configuration.mdx index 7cdc54a..cbbfafb 100644 --- a/docs/configuration/configuration.mdx +++ b/docs/configuration/configuration.mdx @@ -20,7 +20,7 @@ The `base-package` will be scanned for classes containing `@Component` annotated ### `Info` (required) -The `Info` object provides metadata about the API (see [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject). +The `Info` object provides metadata about the API (see [Info Object](https://www.asyncapi.com/docs/reference/specification/v3.0.0#infoObject)). All provided fields will be present in the generated document, but not all will be displayed in the UI. @@ -33,24 +33,6 @@ An AsyncAPI document can contain more than one server, but it's not common. As with the `Info` object, all provided fields will be present in the generated document, but not all will be displayed in the UI. -### `id` - -The `Identifier` value represents a unique universal identifier of the application. See [Identifier](https://www.asyncapi.com/docs/reference/specification/v3.0.0#A2SIdString). - -### `default-content-type` - -A string representing the default content type to use when encoding/decoding a message's payload. See [Default Content Type](https://www.asyncapi.com/docs/reference/specification/v3.0.0#defaultContentTypeString) - -The default is `application/json` and it has an effect on the payload `example` generation. Also supported: `text/xml`, `application/yaml`. - -### Extension Fields - -The AsyncAPI specification allows the definition of additional data fields to extend the -specification at certain points (see [Specification Extensions](https://www.asyncapi.com/docs/reference/specification/v3.0.0#specificationExtensions) ). - -Extension Fields may be added to `Info`, `Contact`, `License` and `Server` objects both via `application.properties`. -Every custom extension field must begin with `x-`, for example `x-internal-id` (see sample configurations above). - ## Additional `application.properties` The following table contains additional properties that can be specified in the `application.properties` file: @@ -58,36 +40,71 @@ The following table contains additional properties that can be specified in the | Property Name | Default Value | Description | |-----------------------------------------------------------------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `springwolf.enabled` | `true` | Allows to enable/disable Springwolf at one central place. | +| `springwolf.docket.default-content-type` | `application/json` | Content type to use when encoding/decoding a message's payload (example generation). Also supported: `text/xml`, `application/yaml`. | +| `springwolf.docket.id` | N/A | The `Identifier` value represents a unique universal identifier of the application. See [Identifier](https://www.asyncapi.com/docs/reference/specification/v3.0.0#A2SIdString). | +| `springwolf.docket.group-config` | N/A | See [Grouping](#grouping) for more details. | +| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. | | `springwolf.init-mode` | `fail_fast` | Springwolf initializes during start up with `fail_fast` or in the `background` after the application has started. | | `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.* | -| `springwolf.endpoint.actuator.enabled` | `false` | Publish the AsyncAPI document as part of Spring Boot’s actuator feature. | -| `springwolf.use-fqn` | `true` | Use fully qualified names for the schema classes. **Required for publishing with `springwolf-ui`** | -| `springwolf.studio-compatibility` | `true` | Activate tweaks to allow viewing & editing in [AsyncAPI studio](https://studio.asyncapi.com) | -| `springwolf.ui.initially-show-bindings` | `true` | Show bindings by default in the UI. | -| `springwolf.ui.initially-show-headers` | `true` | Show headers by default in the UI. | | `springwolf.payload.extractable-classes..` | N/A | Extract additional payload types. See [message payloads](documenting-messages.mdx) for more details. | +| `springwolf.studio-compatibility` | `true` | Activate tweaks to allow viewing & editing in [AsyncAPI studio](https://studio.asyncapi.com) | | `springwolf.scanner.async-listener.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncListener`. | | `springwolf.scanner.async-publisher.enabled` | `true` | Enable scanner to find methods annotated with `@AsyncPublisher`. | -| **AMQP** | | | +| `springwolf.use-fqn` | `true` | Use fully qualified names for the schema classes. **Required for publishing with `springwolf-ui`** | +| **UI** | | | +| `springwolf.ui.defaults.show-bindings` | `true` | Show bindings by default in the UI. | +| `springwolf.ui.defaults.show-headers` | `true` | Show headers by default in the UI. | +| **Plugin: AMQP** | | | | `springwolf.plugin.amqp.publishing.enabled` | `false` | Allow (anyone) to produce AMQP messages from the UI. *Note that this has security implications* | | `springwolf.plugin.amqp.scanner.rabbit-listener.enabled` | `true` | Enable scanner to find methods annotated with `@RabbitListener`. | -| **JMS** | | | +| **Plugin: JMS** | | | | `springwolf.plugin.jms.publishing.enabled` | `false` | Allow (anyone) to produce JMS messages from the UI. *Note that this has security implications* | | `springwolf.plugin.jms.scanner.jms-listener.enabled` | `true` | Enable scanner to find methods annotated with `@JmsListener`. | -| **Kafka** | | | +| **Plugin: Kafka** | | | | `springwolf.plugin.kafka.publishing.enabled` | `false` | Allow (anyone) to produce Kafka messages from the UI. *Note that this has security implications* | | `springwolf.plugin.kafka.publishing.producer` | `null` | Configure the Kafka producer used to publish messages from the UI. Uses identical parameters as `spring.kafka.producer`. [SpringwolfKafkaProducer](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/springwolf/examples/kafka/configuration/CustomSpringwolfKafkaProducer.java#L20) demonstrates multiple producer configuration to publish to Avro and Protobuf. | | `springwolf.plugin.kafka.scanner.kafka-listener.enabled` | `true` | Enable scanner to find methods annotated with `@KafkaListener`. | -| **SNS** | | | +| **Plugin: SNS** | | | | `springwolf.plugin.sns.publishing.enabled` | `false` | Allow (anyone) to produce SNS messages from the UI. *Note that this has security implications* | -| **SQS** | | | +| **Plugin: SQS** | | | | `springwolf.plugin.sqs.publishing.enabled` | `false` | Allow (anyone) to produce SQS messages from the UI. *Note that this has security implications* | | `springwolf.plugin.sqs.scanner.sqs-listener.enabled` | `true` | Enable scanner to find methods annotated with `@SqsListener`. | -| **STOMP (WebSocket)** | | | +| **Plugin: STOMP (WebSocket)** | | | | `springwolf.plugin.stomp.scanner.stomp-message-mapping.enabled` | `true` | Enable scanner to find methods annotated with `@MessageMapping`. | | `springwolf.plugin.stomp.scanner.stomp-send-to.enabled` | `true` | Enable scanner to find methods annotated with `@SendTo`. | | `springwolf.plugin.stomp.scanner.stomp-send-to-user.enabled` | `true` | Enable scanner to find methods annotated with `@SendToUser`. | +## Extension Fields + +The AsyncAPI specification allows the definition of additional data fields to extend the +specification at certain points (see [Specification Extensions](https://www.asyncapi.com/docs/reference/specification/v3.0.0#specificationExtensions) ). + +Extension Fields may be added to `Info`, `Contact`, `License` and `Server` objects both via `application.properties`. +Every custom extension field must begin with `x-`, for example `x-internal-id` (see sample configurations above). + +## Grouping + +The standard AsyncAPI document contains all information, including channels, messages, schemas, etc. + +A group is a filtered view onto specific parts of the AsyncAPI document. + +The group configuration must have a name (`group`). The `info` object can be adjusted and *at most* one matcher can be used: + +| Matcher | Description | Example to filter for | +|-------------------------|--------------------------------------------------------|-------------------------------------------------------------------------------------| +| `channel-name-to-match` | List of regular expressions to match the channel name. | Only public channels: `channel-name-to-match=public-.*` | +| `message-name-to-match` | List of regular expressions to match the message name. | All interactions with a specific payload class: `message-name-to-match=.*Vehicle.*` | +| `action-to-match` | List of `receive`, `send` | Only published messages: `action-to-match=send` | + +Configuration example for the group `Only Vehicles` to only include classes which contain the word `Vehicle` in the class name: + +```properties +springwolf.docket.group-configs[0].group=Only Vehicles +springwolf.docket.group-configs[0].info.description=Group for vehicles. +springwolf.docket.group-configs[0].info.extension-fields.x-apitype=internal +springwolf.docket.group-configs[0].message-name-to-match=.*Vehicle.* +``` + ## Actuator support Springwolf supports exposing the AsyncAPI document as part of Spring Boot’s actuator endpoint. diff --git a/docs/snippets/_springwolf_common_model_converters_groovy.gradle b/docs/snippets/_springwolf_common_model_converters_groovy.gradle index 778aec3..9094d5a 100644 --- a/docs/snippets/_springwolf_common_model_converters_groovy.gradle +++ b/docs/snippets/_springwolf_common_model_converters_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-common-model-converters:1.8.0' + implementation 'io.github.springwolf:springwolf-common-model-converters:1.9.0' } diff --git a/docs/snippets/_springwolf_common_model_converters_maven.xml b/docs/snippets/_springwolf_common_model_converters_maven.xml index f2d9c7d..7206355 100644 --- a/docs/snippets/_springwolf_common_model_converters_maven.xml +++ b/docs/snippets/_springwolf_common_model_converters_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-common-model-converters - 1.8.0 + 1.9.0 diff --git a/docs/snippets/_springwolf_generic_binding_groovy.gradle b/docs/snippets/_springwolf_generic_binding_groovy.gradle index a4769f0..b11c9a4 100644 --- a/docs/snippets/_springwolf_generic_binding_groovy.gradle +++ b/docs/snippets/_springwolf_generic_binding_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-generic-binding:1.8.0' + implementation 'io.github.springwolf:springwolf-generic-binding:1.9.0' } diff --git a/docs/snippets/_springwolf_generic_binding_maven.xml b/docs/snippets/_springwolf_generic_binding_maven.xml index 279391a..fdf39dd 100644 --- a/docs/snippets/_springwolf_generic_binding_maven.xml +++ b/docs/snippets/_springwolf_generic_binding_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-generic-binding - 1.8.0 + 1.9.0 diff --git a/docs/snippets/_springwolf_groovy.gradle b/docs/snippets/_springwolf_groovy.gradle index 1218f6b..0a33f9e 100644 --- a/docs/snippets/_springwolf_groovy.gradle +++ b/docs/snippets/_springwolf_groovy.gradle @@ -1,7 +1,7 @@ dependencies { // Provides the documentation API - implementation 'io.github.springwolf:springwolf-kafka:1.8.0' + implementation 'io.github.springwolf:springwolf-kafka:1.9.0' // Provides the UI - optional (recommended) - runtimeOnly 'io.github.springwolf:springwolf-ui:1.8.0' + runtimeOnly 'io.github.springwolf:springwolf-ui:1.9.0' } diff --git a/docs/snippets/_springwolf_json_schema_groovy.gradle b/docs/snippets/_springwolf_json_schema_groovy.gradle index 183051b..324ede1 100644 --- a/docs/snippets/_springwolf_json_schema_groovy.gradle +++ b/docs/snippets/_springwolf_json_schema_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-json-schema:1.8.0' + implementation 'io.github.springwolf:springwolf-json-schema:1.9.0' } diff --git a/docs/snippets/_springwolf_json_schema_maven.xml b/docs/snippets/_springwolf_json_schema_maven.xml index f458de8..7c5cd77 100644 --- a/docs/snippets/_springwolf_json_schema_maven.xml +++ b/docs/snippets/_springwolf_json_schema_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-json-schema - 1.8.0 + 1.9.0 diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle index 2f43813..9052c34 100644 --- a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.8.0' + implementation 'io.github.springwolf:springwolf-kotlinx-serialization-model-converter:1.9.0' } diff --git a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml index a12c427..b727382 100644 --- a/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml +++ b/docs/snippets/_springwolf_kotlinx_serialization_model_converter_maven.xml @@ -2,6 +2,6 @@ io.github.springwolf springwolf-kotlinx-serialization-model-converter - 1.8.0 + 1.9.0 diff --git a/docs/snippets/_springwolf_maven.xml b/docs/snippets/_springwolf_maven.xml index 2305c52..677c7e8 100644 --- a/docs/snippets/_springwolf_maven.xml +++ b/docs/snippets/_springwolf_maven.xml @@ -3,12 +3,12 @@ io.github.springwolf springwolf-kafka - 1.8.0 + 1.9.0 io.github.springwolf springwolf-ui - 1.8.0 + 1.9.0 diff --git a/src/components/HomepageFeatures.js b/src/components/HomepageFeatures.js index 0ec61e8..35d2924 100644 --- a/src/components/HomepageFeatures.js +++ b/src/components/HomepageFeatures.js @@ -27,7 +27,7 @@ const FeatureList = [ description: ( <> The generated documentation is compliant with the - AsyncAPI specification. + AsyncAPI specification. ), },