ZenWave SDK

ZenWave SDK Helps you Create Software Easy to Understand

Maven Central GitHub release (latest by date) build coverage branches coverage GitHub

The heart of software is its ability to solve domain-related problems for its users. The best software supports elegant solutions to real-world problems - Eric Evans in Domain Driven Design

ZenWave SDK Modeling Languages

ZenWave SDK is a set of tools to convert your Domain Models into working software and tests.

It is designed to be modular, configurable and extensible. It uses the standard java classpath as loading mechanism, so you can extend its functionality adding your own custom plugins. Visit ZenWave SDK for all configuration options.

Based on Domain Driven Design (DDD) and API-First principles for Event Driven Microservices.

Speed Feedback Loop

ZenWave SDK can generate code from a mix of different models including:

  • ZDL Domain Language as Ubiquitous Language. You can describe the core of your Bounded Context, as well as how it connects to external systems through different adapters and APIs.
  • AsyncAPI: Industry de-facto standard to describe Event-Driven Architectures for Message-based APIs.
  • OpenAPI: Industry standard for Request-Response Architectures with REST APIs.

Using ZenWave Domain Language as Ubiquitous Language for modeling and describing Bounded Contexts: aggregates, entities with their relationships, services, value objects, commands and events.

ZenWave Domain Language started as an extended subset of JHipster Domain Language (JDL) that let you describe your entities and relationships.

Using ZDL Domain Language as Ubiquitous Language for Data on the Inside and API-First specs like AsyncAPI and OpenAPI to describe Inter Process Communications (IPC) for Data on the Outside.

  • ZenWave Domain Language (ZDL) as Ubiquitous Language: To describe your domain core domain model.
  • API-First specs like AsyncAPI and OpenAPI: to describe Inter Process Communications (IPC) between bounded contexts/microservices.
  • ZenWave SDK: to generate (a lot of) infrastructure, functional and testing code from your models and APIs.

ZenWave SDK is designed to be easily extensible and adaptable to your project or your organization needs and likes.

ZenWave SDK Installation

Command Line Interface (CLI)

You can install the latest release using jbang running the following command:

jbang alias add --fresh --name=zw release@zenwave360/zenwave-sdk
jbang zw --help list

Will output a list of all available plugins:

ZW> SDK (1.4.0)
Available plugins:
backend-application-default io.zenwave360.sdk.plugins.BackendApplicationDefaultPlugin: Generates a full backend application using a flexible hexagonal architecture (1.4.0)
spring-cloud-streams3-adapters io.zenwave360.sdk.plugins.SpringCloudStreams3AdaptersPlugin: Generates tests for Spring Cloud Streams Consumers. (1.4.0)
jdl-to-asyncapi io.zenwave360.sdk.plugins.JDLToAsyncAPIPlugin: Generates a full AsyncAPI definitions for CRUD operations from JDL models (1.4.0)
spring-webtestclient io.zenwave360.sdk.plugins.SpringWebTestClientPlugin: Generates test for SpringMVC or Spring WebFlux using WebTestClient based on OpenAPI specification. (1.4.0)
fork-plugin io.zenwave360.sdk.plugins.ForkPlugin: Creates a new standalone maven module cloning an existing plugin (1.4.0)
jsonschema2pojo io.zenwave360.sdk.plugins.AsyncApiJsonSchema2PojoPlugin: Generate Plain Old Java Objects from OpenAPI/AsyncAPI schemas or full JSON-Schema files (1.4.0)
openapi-controllers io.zenwave360.sdk.plugins.OpenAPIControllersPlugin: Generates implementations based on ZDL models and OpenAPI definitions SpringMVC generated OpenAPI interfaces. (1.4.0)
openapi-to-jdl io.zenwave360.sdk.plugins.OpenAPIToJDLPlugin: Generates JDL model from OpenAPI schemas (1.4.0)
spring-cloud-streams3 io.zenwave360.sdk.plugins.SpringCloudStreams3Plugin: Generates strongly typed SpringCloudStreams3 producer/consumer classes for AsyncAPI (1.4.0)
rest-assured io.zenwave360.sdk.plugins.RestAssuredPlugin: Generates REST-Assured tests based on OpenAPI specification. (1.4.0)
zdl-to-openapi io.zenwave360.sdk.plugins.ZDLToOpenAPIPlugin: Generates a draft OpenAPI definitions from your ZDL entities and services. (1.4.0)
zdl-to-markdown io.zenwave360.sdk.plugins.ZdlToMarkdownPlugin: Generates Markdown glossary from Zdl Models (1.4.0)
zdl-to-asyncapi io.zenwave360.sdk.plugins.ZDLToAsyncAPIPlugin: Generates a draft AsyncAPI file with events from your ZDL services. (1.4.0)
Use: "jbang zw -p <plugin | short-code> -h" to get help on a specific plugin

If you don't find the functionality you are looking for, you can always fork an existing, standard or custom plugin.

Please refer to ZenWave SDK for more detailed installation options.

Maven Plugin

You can run any available (standard or custom) plugin as part of your maven build using the maven plugin:

Click to see the maven plugin configuration
<includeProjectClasspath>false</includeProjectClasspath><!-- default is false -->
<addCompileSourceRoot>true</addCompileSourceRoot><!-- default is true -->
<addTestCompileSourceRoot>true</addTestCompileSourceRoot><!-- default is true -->
<!-- Add executions for each generation here: -->
<!-- ... -->
<!-- add any sdk plugin (custom or standard) as dependency here -->

Notice how you can read spec files from the project classpath as well as the filesystem. If you want to read a spec file from inside a project dependency remember to set <includeProjectClasspath>true</includeProjectClasspath>.

NOTE: Remember to add any plugin you want to use as dependency.

Jump to ZenWave AsyncAPI Generator for multiple examples using the maven plugin.

ZenWave SDK Workflow

You can generate complete Event Driven Microservices using DDD and API-First principles:

πŸ‘‰ Describe your Domain Model β€³ Generate OpenAPI β€³ Generate AsyncAPI β†’ Generate API Implementations β†’ Generate Backend β†’ Generate Tests and Contracts πŸ‘

  1. Start by Modeling your Domain using the ZDL Domain Language including: entities, relationships, service commands and domain events.
  2. Generate a draft OpenAPI definition from the ZDL model. Edit collaboratively this OpenAPI document and then generate some more functional code and tests from that definition.
  3. Generate a draft AsyncAPI definition for consuming async request commands and publishing domain events. Now use zenwave maven plugin to generate strongly typed business interfaces implementing some Enterprise Integration Patterns like: transactional outbox, business dead letter queue...
  4. Generate a complete Backend Application from your Domain Definition Model.
  5. Connect (by hand) your Backend Application to other systems using the generated OpenAPI and AsyncAPI definitions.
  6. Generate E2E, Integration tests and Consumer Contracts for the public APIs you just produced.
ZenWave SDK Features MindMap
ZenWave SDK Code Generator Features (expand to see)
  • JDL Backend Application (flexible hexagonal architecture)
    • Domain Entities,
    • Inbound
      • Service Ports, DTOs, Mappers
      • Implementation for CRUD operations
      • Acceptance Tests: SpringData InMemory Repositories
    • Outbound: SpringData Repositories, ElasticSearch... (for REST or Async see other plugins)
    • Adapters:
      • Spring MVC
      • Spring WebFlux
    • Flavors
      • MongoDB
        • Imperative
        • Reactive
      • JPA
        • Imperative
        • Reactive
    • Unit/Integration Testing
      • Edge Integration Testing: partial spring-boot context for outbound adapters (with testcontainers)
      • Sociable Vertical Testing: manual dependency setup with in memory infrastructure test-doubles
      • Vertical Integration Testing: full spring-boot context for inbound adapters (with testcontainers)
  • JDL OpenAPI Controllers
  • OpenAPI to Spring WebTestClient
  • AsyncAPI Spring Cloud Streams3
    • Consumer and Producer. Imperative and Reactive.
      • Business Exceptions Dead Letter Queues Routing
    • Producer with Transactional Outbox pattern
      • For MongoDB
      • For JDBC
    • Enterprise Envelop Pattern
    • Automatically fill headers at runtime from payload paths, tracing-id supplier...
  • JDL to Specs
    • JDL to OpenAPI
    • JDL to AsyncAPI
      • AsyncAPI schemas
      • AVRO schemas
  • API Testing
  • Reverser Engineering
    • OpenAPI 2 JDL
    • Java 2 JDL
      • Spring Data MongoDB annotations
      • JPA annotations

Generated Code Structure

Generated code follows a flexible onion/hexagonal architecture. Separating core, inbound, implementation and outbound form infrastructure and adapters.

Core domain entities and aggregates are annotated for persistence with JPA or SpringData/MongoDB annotations, avoiding unnecessary translation layers (mappers and dtos).

ZenWave SDK Modeling Languages

Project structure:

πŸ“¦ <basePackage>
πŸ“¦ adapters
└─ web
| └─ RestControllers (spring mvc)
└─ events
└─ *EventListeners (spring-cloud-streams)
πŸ“¦ core
β”œβ”€ πŸ“¦ domain
| └─ (entities and aggregates)
β”œβ”€ πŸ“¦ inbound
| β”œβ”€ dtos/
| └─ ServiceInterface (inbound service interface)
β”œβ”€ πŸ“¦ outbound
| β”œβ”€ mongodb
| | └─ *RepositoryInterface (spring-data interface)
| └─ jpa
| └─ *RepositoryInterface (spring-data interface)
└─ πŸ“¦ implementation
β”œβ”€ mappers/
└─ ServiceImplementation (inbound service implementation)
πŸ“¦ infrastructure
β”œβ”€ mongodb
| └─ CustomRepositoryImpl (spring-data custom implementation)
└─ jpa
└─ CustomRepositoryImpl (spring-data custom implementation)
ZenWave SDK Generated Code Screenshot