Documenting Application Modules :: Spring Modulith
Why Spring
Overview
Trending
Generative AI
Cloud
Architecture Patterns
Microservices
Reactive
Event Driven
Application Types
Web Applications
Serverless
Batch
Learn
Getting Started
Quickstart
Guides
Academy
Courses
Get Certified
Projects
Overview
Projects
Spring Boot
Spring Framework
Spring Cloud
Spring AI
Spring Data
Spring Integration
Spring Batch
Spring Security
Foundational Projects
Micrometer
Reactor
Development Tools
Spring Tools
Spring Initializr
Resources
Blog
Release Calendar
Version Mappings
Release Highlights
Security Advisories
GitHub Orgs
Spring Projects
Spring Cloud
Community
Overview
Events
Authors
Enterprise
Overview
Long-term Support
Automated Upgrades
Governance and Compliance
Modern App Development
light
Spring Modulith
2.1.0
Search
Overview
Fundamentals
Verifying Application Module Structure
Working with Application Events
Integration Testing Application Modules
Moments — a Passage of Time Events API
Documenting Application Modules
Spring Modulith Runtime Support
Production-ready Features
Appendix
Search
Edit this Page
GitHub Project
Spring Modulith
Documenting Application Modules
Documenting Application Modules
The application module model created via ApplicationModules can be used to create documentation snippets for inclusion into developer documentation written in Asciidoc.
Spring Modulith’s Documenter abstraction can produce two different kinds of snippets:
C4 and UML component diagrams describing the relationships between the individual application modules
A so-called Application Module Canvas, a tabular overview about the module and the most relevant elements in those (Spring beans, aggregate roots, events published and listened to as well as configuration properties).
Additionally, Documenter can produce an aggregating Asciidoc file that includes all existing component diagrams and canvases.
Generating Application Module Component diagrams
The documentation snippets can be generated by handing the ApplicationModules instance into a Documenter.
Generating application module component diagrams using Documenter
Java
Kotlin
class DocumentationTests {
ApplicationModules modules = ApplicationModules.of(Application.class);
@Test
void writeDocumentationSnippets() {
new Documenter(modules)
.writeModulesAsPlantUml()
.writeIndividualModulesAsPlantUml();
}
}
class DocumentationTests {
private val modules = ApplicationModules.of(Application::class.java)
@Test
fun writeDocumentationSnippets() {
Documenter(modules)
.writeModulesAsPlantUml()
.writeIndividualModulesAsPlantUml()
}
}
The first call on Documenter will generate a C4 component diagram containing all modules within the system.
Figure 1. All modules and their relationships rendered as C4 component diagram
The second call will create additional diagrams that only include the individual module and the ones they directly depend on the canvas.
Figure 2. A subset of application modules and their relationships starting from the order module rendered as C4 component diagram
Using Traditional UML Component Diagrams
If you prefer the traditional UML style component diagrams, tweak the DiagramOptions to rather use that style as follows:
Java
Kotlin
DiagramOptions.defaults()
.withStyle(DiagramStyle.UML);
DiagramOptions.defaults()
.withStyle(DiagramStyle.UML)
This will cause the diagrams to look like this:
Figure 3. All modules and their relationships rendered as UML component diagram
Figure 4. A subset of application modules and their relationships starting from the order module rendered as UML component diagram
Generating Application Module Canvases
The Application Module Canvases can be generated by calling Documenter.writeModuleCanvases():
Generating application module canvases using Documenter
Java
Kotlin
class DocumentationTests {
ApplicationModules modules = ApplicationModules.of(Application.class);
@Test
void writeDocumentationSnippets() {
new Documenter(modules)
.writeModuleCanvases();
}
}
class DocumentationTests {
private val modules = ApplicationModules.of(Application::class.java)
@Test
fun writeDocumentationSnippets() {
Documenter(modules)
.writeModuleCanvases()
}
}
By default, the documentation will be generated to spring-modulith-docs folder in your build system’s build folder.
A generated canvas looks like this:
Table 1. A sample Application Module Canvas
Base package
com.acme.commerce.inventory
Spring components
Services
c.a.c.i.InventoryManagement
Repositories
c.a.c.i.Inventory
Event listeners
c.a.c.i.InternalInventoryListeners listening to o.s.m.m.DayHasPassed, c.a.c.i.QuantityReduced
c.a.c.i.InventoryOrderEventListener listening to c.a.c.o.OrderCanceled, c.a.c.o.OrderCompleted
Configuration properties
c.a.c.i.InventoryProperties
Others
c.a.c.i.InventoryItemCreationListener
Aggregate roots
c.a.c.i.InventoryItem
Published events
c.a.c.i.QuantityReduced created by:
c.a.c.i.InventoryItem.decreaseQuantity(…)
c.a.c.i.StockShort created by:
c.a.c.i.InternalInventoryListeners.on(…)
Events listened to
c.a.c.o.OrderCompleted
c.a.c.o.OrderCanceled
Properties
acme.commerce.inventory.restock-threshold — c.a.c.c.Quantity. The threshold at which a InventoryEvents.StockShort is supposed to be triggered during inventory updates.
It consists of the following sections:
The application module’s base package.
The Spring beans exposed by the application module, grouped by stereotype. — In other words, beans that are located in either the API package or any named interface package.
This will detect component stereotypes defined by jMolecules architecture abstractions, but also standard Spring stereotype annotations.
Exposed aggregate roots — Any entities that we find repositories for or explicitly declared as aggregate via jMolecules.
Application events published by the module — Those event types need to be demarcated using jMolecules @DomainEvent or implement its DomainEvent interface.
Application events listened to by the module — Derived from methods annotated with Spring’s @EventListener, @TransactionalEventListener, jMolecules' @DomainEventHandler or beans implementing ApplicationListener.
Configuration properties — Spring Boot Configuration properties exposed by the application module.
Requires the usage of the spring-boot-configuration-processor artifact to extract the metadata attached to the properties.
Generating an Aggregating Document
When using Documenter.writeDocumentation(…) an all-docs.adoc file will be generated, linking all generated diagrams and Application Module Canvases.
We can manually generate the aggregating document by calling Documenter.writeAggregatingDocument():
Generating an aggregating document using Documenter
Java
Kotlin
class DocumentationTests {
ApplicationModules modules = ApplicationModules.of(Application.class);
@Test
void writeDocumentationSnippets() {
new Documenter(modules)
.writeAggregatingDocument();
}
}
class DocumentationTests {
private val modules = ApplicationModules.of(Application::class.java)
@Test
fun writeDocumentationSnippets() {
Documenter(modules)
.writeAggregatingDocument()
}
}
The aggregating document will include any existing application module component diagrams and application module canvases.
If there are none, then this method will not produce an output file.
Moments — a Passage of Time Events API
Spring Modulith Runtime Support
Spring Modulith
Stable
2.1.0
2.0.7
1.4.12
1.3.12
1.2.13
1.1.12
Snapshot
2.2.0-SNAPSHOT
2.1.1-SNAPSHOT
2.0.8-SNAPSHOT
1.4.13-SNAPSHOT
1.3.13-SNAPSHOT
1.2.14-SNAPSHOT
1.1.13-SNAPSHOT
Related Spring Documentation
Spring Boot
Spring Framework
Spring Cloud
Spring Cloud Build
Spring Cloud Bus
Spring Cloud Circuit Breaker
Spring Cloud Commons
Spring Cloud Config
Spring Cloud Consul
Spring Cloud Contract
Spring Cloud Function
Spring Cloud Gateway
Spring Cloud Kubernetes
Spring Cloud Netflix
Spring Cloud OpenFeign
Spring Cloud Stream
Spring Cloud Task
Spring Cloud Vault
Spring Cloud Zookeeper
Spring Data
Spring Data Cassandra
Spring Data Commons
Spring Data Couchbase
Spring Data Elasticsearch
Spring Data JPA
Spring Data KeyValue
Spring Data LDAP
Spring Data MongoDB
Spring Data Neo4j
Spring Data Redis
Spring Data JDBC & R2DBC
Spring Data REST
Spring Integration
Spring Batch
Spring Security
Spring Authorization Server
Spring LDAP
Spring Security Kerberos
Spring Session
Spring Vault
Spring AI
Spring AMQP
Spring CLI
Spring GraphQL
Spring for Apache Kafka
Spring Modulith
Spring for Apache Pulsar
Spring Shell
All Docs...
Copyright © 2005 -
Broadcom. All Rights Reserved. The term "Broadcom" refers to Broadcom Inc. and/or its subsidiaries.
Terms of Use • Privacy • Trademark Guidelines • Thank you • Your California Privacy Rights • Cookie Settings
Apache®, Apache Tomcat®, Apache Kafka®, Apache Cassandra™, and Apache Geode™ are trademarks or registered trademarks of the Apache Software Foundation in the United States and/or other countries. Java™, Java™ SE, Java™ EE, and OpenJDK™ are trademarks of Oracle and/or its affiliates. Kubernetes® is a registered trademark of the Linux Foundation in the United States and other countries. Linux® is the registered trademark of Linus Torvalds in the United States and other countries. Windows® and Microsoft® Azure are registered trademarks of Microsoft Corporation. “AWS” and “Amazon Web Services” are trademarks or registered trademarks of Amazon.com Inc. or its affiliates. All other trademarks and copyrights are property of their respective owners and are only mentioned for informative purposes. Other names may be trademarks of their respective owners.
Search in all Spring Docs