|
| 1 | +# AsyncAPI and Spring Cloud Stream with Avro and JSON |
| 2 | +> 👉 ZenWave360 Helps You Create Software Easy to Understand |
| 3 | +
|
| 4 | +[](https://search.maven.org/artifact/io.zenwave360.sdk/zenwave-sdk) |
| 5 | +[](https://github.com/ZenWave360/zenwave-sdk/blob/main/LICENSE) |
| 6 | + |
| 7 | +Generates strongly typed SpringCloudStreams3 producer/consumer classes for AsyncAPI with Avro and JSON DTOs |
| 8 | + |
| 9 | +## Maven Usage |
| 10 | + |
| 11 | +- Configure `zenwave-sdk-maven-plugin` in your `pom.xml` |
| 12 | +- Add `asyncapi-spring-cloud-streams-with-avro-json` as dependency to `zenwave-sdk-maven-plugin` |
| 13 | +- Bring your own version of `avro-compiler` as dependency to `zenwave-sdk-maven-plugin`, supporting versions 1.8.0 - 1.12.0+ |
| 14 | +- Include maven dependencies holding your API files in case you are using `classpath:` scheme in `inputSpec`. |
| 15 | +- Set `<generatorName>SpringCloudStreamsWithDtosPlugin</generatorName>` |
| 16 | +- Point to your AsyncAPI file in `inputSpec`: supported schemes are `classpath:`, `https://` and regular local files. |
| 17 | +- Configure basic options: |
| 18 | + - `producerApiPackage`,`consumerApiPackage`: producer/consumer packages (for events/commands respectively) |
| 19 | + - `modelPackage`: package for generated DTOs in case of JSON payloads |
| 20 | + - `avroCompilerProperties.*`: options like `imports`, `includes`, `excludes`, `customLogicalTypeFactories`, `customConversions`, etc... See [AvroCompilerProperties](https://github.com/ZenWave360/zenwave-sdk/blob/main/plugins/avro-schema-compiler/src/main/java/io/zenwave360/sdk/plugins/AvroCompilerProperties.java) |
| 21 | + - `jsonschema2pojo.*`: JsonSchema2Pojo settings for downstream library. See [JsonSchema2PojoConfiguration.java](https://github.com/ZenWave360/zenwave-sdk/blob/main/plugins/asyncapi-jsonschema2pojo/src/main/java/io/zenwave360/sdk/plugins/JsonSchema2PojoConfiguration.java) |
| 22 | + |
| 23 | +```xml |
| 24 | +<plugin> |
| 25 | + <groupId>io.zenwave360.sdk</groupId> |
| 26 | + <artifactId>zenwave-sdk-maven-plugin</artifactId> |
| 27 | + <version>${zenwave.version}</version> |
| 28 | + <configuration> |
| 29 | + <addCompileSourceRoot>true</addCompileSourceRoot><!-- default is true --> |
| 30 | + <addTestCompileSourceRoot>true</addTestCompileSourceRoot><!-- default is true --> |
| 31 | + </configuration> |
| 32 | + <executions> |
| 33 | + <execution> |
| 34 | + <id>generate-asyncapi-with-dtos</id> |
| 35 | + <phase>generate-sources</phase> |
| 36 | + <goals> |
| 37 | + <goal>generate</goal> |
| 38 | + </goals> |
| 39 | + <configuration> |
| 40 | + <generatorName>SpringCloudStreamsWithDtosPlugin</generatorName> |
| 41 | + <inputSpec>classpath:model/asyncapi.yml</inputSpec><!-- supported schemes are `classpath:`, `https://` and regular local files --> |
| 42 | + <configOptions> |
| 43 | + <producerApiPackage>io.example.api.producer</producerApiPackage> |
| 44 | + <consumerApiPackage>io.example.api.consumer</consumerApiPackage> |
| 45 | + |
| 46 | + <avroCompilerProperties.imports>classpath:avro</avroCompilerProperties.imports><!-- supports local files/folders, `classpath:` files/folders or `https://` file resources --> |
| 47 | + |
| 48 | + <modelPackage>io.example.api.model</modelPackage> |
| 49 | + <jsonschema2pojo.includeTypeInfo>true</jsonschema2pojo.includeTypeInfo> |
| 50 | + |
| 51 | + <transactionalOutbox>modulith</transactionalOutbox> |
| 52 | + </configOptions> |
| 53 | + </configuration> |
| 54 | + </execution> |
| 55 | + </executions> |
| 56 | + <dependencies> |
| 57 | + <dependency> |
| 58 | + <groupId>io.zenwave360.sdk.plugins</groupId> |
| 59 | + <artifactId>asyncapi-spring-cloud-streams-with-avro-json</artifactId> |
| 60 | + <version>${zenwave.version}</version><!-- 2.2.0+ --> |
| 61 | + </dependency> |
| 62 | + <dependency> |
| 63 | + <groupId>org.apache.avro</groupId> |
| 64 | + <artifactId>avro-compiler</artifactId> |
| 65 | + <version>${avro-compiler.version}</version><!-- 1.8.0 - 1.12.0+ --> |
| 66 | + </dependency> |
| 67 | + </dependencies> |
| 68 | +</plugin> |
| 69 | +``` |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +## Options |
| 74 | + |
| 75 | +| **Option** | **Description** | **Type** | **Default** | **Values** | |
| 76 | +|-----------------------------------------------------|-----------------|----------|-------------|------------| |
| 77 | +| `apiFile` | API Specification File | URI | | | |
| 78 | +| `role` | Project role: provider/client | AsyncapiRoleType | provider | provider, client | |
| 79 | +| `style` | Programming style | ProgrammingStyle | imperative | imperative, reactive | |
| 80 | +| `modelPackage` | Java Models package name | String | | | |
| 81 | +| `producerApiPackage` | Java API package name for outbound (producer) services. It can override apiPackage for producers. | String | {{apiPackage}} | | |
| 82 | +| `consumerApiPackage` | Java API package name for inbound (consumer) services. It can override apiPackage for consumer. | String | {{apiPackage}} | | |
| 83 | +| `apiPackage` | Java API package, if `producerApiPackage` and `consumerApiPackage` are not set. | String | | | |
| 84 | +| `jsonschema2pojo` | JsonSchema2Pojo settings for downstream library [(docs)](https://github.com/ZenWave360/zenwave-sdk/blob/main/plugins/asyncapi-jsonschema2pojo/src/main/java/io/zenwave360/sdk/plugins/JsonSchema2PojoConfiguration.java) | Map | {} | | |
| 85 | +| `avroCompilerProperties` | Avro Compiler Properties | AvroCompilerProperties | See [AvroCompilerProperties](https://github.com/ZenWave360/zenwave-sdk/blob/main/plugins/avro-schema-compiler/src/main/java/io/zenwave360/sdk/plugins/AvroCompilerProperties.java) | | |
| 86 | +| `avroCompilerProperties.sourceDirectory` | Avro schema file or folder containing avro schemas | File | | | |
| 87 | +| `avroCompilerProperties.imports` | Avro schema files or folders containing avro schemas. It supports local files/folders, `classpath:` files/folders or `https://` file resources. | List | | | |
| 88 | +| `avroCompilerProperties.includes` | A set of Ant-like inclusion patterns used to select files from the source tree that are to be processed. By default, the pattern **\/*.avsc is used to include all avro schema files. | List | [**/*.avsc] | | |
| 89 | +| `avroCompilerProperties.excludes` | A set of Ant-like exclusion patterns used to prevent certain files from being processed. By default, this set is empty such that no files are excluded. | List | | | |
| 90 | +| `avroCompilerProperties.customLogicalTypeFactories` | Custom Logical Type Factories | List | | | |
| 91 | +| `avroCompilerProperties.customConversions` | Custom Conversions | List | | | |
| 92 | +| `operationIds` | Operation ids to include in code generation. Generates code for ALL if left empty | List | [] | | |
| 93 | +| `messageNames` | Message names to include in code generation (combined with operationIds). Generates code for ALL if left empty | List | [] | | |
| 94 | +| `excludeOperationIds` | Operation ids to exclude in code generation. Skips code generation if is not included or is excluded. | List | [] | | |
| 95 | +| `bindingTypes` | Binding names to include in code generation. Generates code for ALL bindings if left empty | List | | | |
| 96 | +| **JsonSchema2Pojo Options** | | | | | |
| 97 | +| `modelNamePrefix` | Sets the prefix for model classes and enums | String | | | |
| 98 | +| `modelNameSuffix` | Sets the suffix for model classes and enums | String | | | |
| 99 | +| `generatedAnnotationClass` | Annotation class to mark generated code (e.g. `org.springframework.aot.generate.Generated`). When retained at runtime, this prevents code coverage tools like Jacoco from including generated classes in coverage reports. | String | | | |
| 100 | +| **SpringCloudStreams3 Options** | | | | | |
| 101 | +| `transactionalOutbox` | Transactional outbox type for message producers. | TransactionalOutboxType | none | none, modulith, mongodb, jdbc | |
| 102 | +| `bindingPrefix` | SC Streams Binding Name Prefix (used in @Component name) | String | | | |
| 103 | +| `bindingSuffix` | Spring-Boot binding suffix. It will be appended to the operation name kebab-cased. E.g. <operation-id>-in-0 | String | -0 | | |
| 104 | +| `runtimeHeadersProperty` | AsyncAPI extension property name for runtime auto-configuration of headers. | String | x-runtime-expression | | |
| 105 | +| `includeApplicationEventListener` | Include ApplicationEvent listener for consuming messages within the modulith. | boolean | false | | |
| 106 | +| `skipProducerImplementation` | Generate only the producer interface and skip the implementation. | boolean | false | | |
| 107 | +| `exposeMessage` | Whether to expose underlying spring Message to consumers or not. | boolean | false | | |
| 108 | +| `useEnterpriseEnvelope` | Include support for enterprise envelop wrapping/unwrapping. | boolean | false | | |
| 109 | +| `envelopeJavaTypeExtensionName` | AsyncAPI Message extension name for the envelop java type for wrapping/unwrapping. | String | x-envelope-java-type | | |
| 110 | +| `methodAndMessageSeparator` | To avoid method erasure conflicts, when exposeMessage or reactive style this character will be used as separator to append message payload type to method names in consumer interfaces. | String | $ | | |
| 111 | +| `consumerPrefix` | SC Streams Binder class prefix | String | | | |
| 112 | +| `consumerSuffix` | SC Streams Binder class suffix | String | Consumer | | |
| 113 | +| `consumerServicePrefix` | Business/Service interface prefix | String | I | | |
| 114 | +| `consumerServiceSuffix` | Business/Service interface suffix | String | ConsumerService | | |
| 115 | +| **General Options** | | | | | |
| 116 | +| `sourceFolder` | Source folder inside folder to generate code to. | String | src/main/java | | |
| 117 | +| `targetFolder` | Target folder to generate code to. If left empty, it will print to stdout. | File | | | |
| 118 | +| `formatter` | Code formatter implementation | Formatters | palantir | palantir, spring, google | |
| 119 | +| `skipFormatting` | Skip java sources output formatting | boolean | false | | |
| 120 | +| `haltOnFailFormatting` | Halt on formatting errors | boolean | true | | |
| 121 | + |
| 122 | +## Getting Help |
| 123 | + |
| 124 | +```shell |
| 125 | +jbang zw -p io.zenwave360.sdk.plugins.AsyncAPIGeneratorPlugin`` |
0 commit comments