6. 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:spring-doc.cn

  • C4 and UML component diagrams describing the relationships between the individual application modulesspring-doc.cn

  • 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).spring-doc.cn

6.1. Generating Application Module Component diagrams

The documentation snippets can be generated by handing the ApplicationModules instance into a Documenter.spring-doc.cn

Generating application module component diagrams using Documenter
class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new Documenter(modules)
      .writeModulesAsPlantUml()
      .writeIndividualModulesAsPlantUml();
  }
}

The first call on Documenter will generate a C4 component diagram containing all modules within the system.spring-doc.cn

c4 all modules
Figure 3. 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 on the canvas.spring-doc.cn

c4 individual modules
Figure 4. A subset of application modules and their relationships starting from the order module rendered as C4 component diagram

6.1.1. Using Traditional UML Component Diagrams

If you prefer the traditional UML style component diagrams, tweak the DiagramOptions to rather use that style as follows:spring-doc.cn

DiagramOptions.defaults()
  .withStyle(DiagramStyle.UML);

This will cause the diagrams to look like this:spring-doc.cn

uml all modules
Figure 5. All modules and their relationships rendered as UML component diagram
uml individiual module
Figure 6. A subset of application modules and their relationships starting from the order module rendered as UML component diagram

6.2. Generating Application Module Canvases

The Application Module Canvases can be generated by calling Documenter.writeModuleCanvases():spring-doc.cn

Generating application module canvases using Documenter
class DocumentationTests {

  ApplicationModules modules = ApplicationModules.of(Application.class);

  @Test
  void writeDocumentationSnippets() {

    new 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:spring-doc.cn

Table 2. A sample Application Module Canvas

Base packagespring-doc.cn

com.acme.commerce.inventoryspring-doc.cn

Spring componentsspring-doc.cn

Servicesspring-doc.cn

Repositoriesspring-doc.cn

Event listenersspring-doc.cn

  • c.a.c.i.InternalInventoryListeners listening to o.s.m.m.DayHasPassed, c.a.c.i.QuantityReducedspring-doc.cn

  • c.a.c.i.InventoryOrderEventListener listening to c.a.c.o.OrderCanceled, c.a.c.o.OrderCompletedspring-doc.cn

Configuration propertiesspring-doc.cn

Othersspring-doc.cn

Aggregate rootsspring-doc.cn

Published eventsspring-doc.cn

Events listened tospring-doc.cn

Propertiesspring-doc.cn

  • 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.spring-doc.cn

It consists of the following sections:spring-doc.cn

  • The application module’s base package.spring-doc.cn

  • 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.spring-doc.cn

  • Exposed aggregate roots — Any entities that we find repositories for or explicitly declared as aggregate via jMolecules.spring-doc.cn

  • Application events published by the module — Those event types need to be demarcated using jMolecules @DomainEvent or implement its DomainEvent interface.spring-doc.cn

  • Application events listened to by the module — Derived from methods annotated with Spring’s @EventListener, @TransactionalEventListener, jMolecules' @DomainEventHandler or beans implementing ApplicationListener.spring-doc.cn

  • 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.spring-doc.cn