References
CPS-1796 - Getting issue details... STATUS
Assumptions<optional>
<optional, assumptions are like decision made up front ie. everyone agrees on the answer but they are important to mention>
| # | Assumption | Notes |
|---|---|---|
| 1 |
Issues & Decisions
| # | Issue | Notes | Decision |
|---|---|---|---|
| 1 | This is an open issue | ||
| 2 | Do we need a analysis template? | is convention for (new) developers to guide them | Luke Gleeson and Toine Siebelink agreed we do to have consistent study pages |
| 3 | This is a very important (blocking issue) |
<Note. use green for closed issues, yellow for important ones if needed>
AsyncAPI
Parser
The parser is used to validate AsynAPI documents. AsyncAPI documents can be written in either YAML or JSON. There are parsers available for various programming languages including Go, C# and Javascript. For CPS we would leverage the AsyncAPI Parser Java Wrapper.
Template
A template is a project that specifies the generation process output by using the AsyncAPI generator and an AsyncAPI document. These files describe the generation results depending on the AsyncAPI document's content. Relevant outputs include Code and Documentation.
A template is an independent Node.js project unrelated to the generator repository. There are Java, Java Spring and Java Spring Cloud Stream templates. Templates.
Generator
The AsyncAPI generator is a tool that generates anything you want using the AsyncAPI Document and Template that are supplied as inputs to the AsyncAPI CLI. The template can define code, documentation and diagrams among other things to be generated with the generator.
Servers
servers:
production:
url: kafka.bootstrap:{port}
protocol: kafka
variables:
port:
default: '9092'
enum:
- '9092'
- '9093'
Channels
A channel is a mechanism created by the server for the organization and transmission of messages. Users can define channels as a topic, queue, routing key, path, or subject depending on the protocol used.
channels:
event.lighting.measured:
publish:
bindings:
kafka:
groupId: my-group
operationId: readLightMeasurement
message:
$ref: '#/components/messages/lightMeasured'
subscribe:
operationId: updateLightMeasurement
message:
$ref: '#/components/messages/lightMeasured'
Example AsyncAPI Document
ZenWave SDK
ZenWave 360º is a set of tools built on the foundations of Domain Driven Design and API-First principles for Event-Driven Architectures, to help you create software easy to understand.
With ZenWave's spring-cloud-streams3 and jsonschema2pojo sdk plugins you can generate:
- Strongly typed business interfaces
- Payload DTOs
- Header objects from AsyncAPI definitions.
- It uses Spring Cloud Streams, so it can connect to different brokers via provided binders.
Using the kafka.yml the pom.xml can be configured to create DTO's:
<plugin>
<groupId>io.github.zenwave360.zenwave-sdk</groupId>
<artifactId>zenwave-sdk-maven-plugin</artifactId>
<version>1.3.5</version>
<configuration>
<skip>false</skip>
<inputSpec>${project.basedir}/src/main/resources/asyncapi.yml</inputSpec>
<addCompileSourceRoot>true</addCompileSourceRoot>
<addTestCompileSourceRoot>true</addTestCompileSourceRoot>
</configuration>
<executions>
<execution>
<id>generate-asyncapi-dtos</id>
<phase>generate-sources</phase>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<generatorName>jsonschema2pojo</generatorName>
<configOptions>
<jsonschema2pojo.removeOldOutput>true</jsonschema2pojo.removeOldOutput>
<jsonschema2pojo.useJakartaValidation>true</jsonschema2pojo.useJakartaValidation>
<modelPackage>com.example.asyncmethod.models</modelPackage>
<apiPackage>com.example.asyncmethod.api</apiPackage>
<jsonschema2pojo.useLongIntegers>true</jsonschema2pojo.useLongIntegers>
</configOptions>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>io.github.zenwave360.zenwave-sdk.plugins</groupId>
<artifactId>asyncapi-spring-cloud-streams3</artifactId>
<version>1.3.5</version>
</dependency>
<dependency>
<groupId>io.github.zenwave360.zenwave-sdk.plugins</groupId>
<artifactId>asyncapi-jsonschema2pojo</artifactId>
<version>1.3.5</version>
</dependency>
<dependency>
<groupId>jakarta.validation</groupId>
<artifactId>jakarta.validation-api</artifactId>
<version>3.0.2</version>
</dependency>
</dependencies>
</plugin>
Problem
The useJakartaValidation configuration option does not appear to work. This results in generated code using javax.validation that does not always work with Java 17.