Documentation, endpoint and Dev UI
Quarkus Modulith writes the documentation Spring Modulith’s Documenter writes: C4 or UML component diagrams, a canvas per module, an aggregating document and the module metadata. The build writes it for the running application, and a Documenter writes it from a plain test.
Generated documentation
When the application is packaged, the build writes to target/modulith-docs (quarkus.modulith.docs.output-directory):
| File | Content |
|---|---|
|
PlantUML component diagram of all modules, C4 style by default. |
|
One diagram per module with the modules it depends on. |
|
The module canvas: description (from the package Javadoc), base package, components grouped by role, bean references, aggregate roots, value types, published events with the methods creating them, events listened to, configuration properties. |
|
Includes every diagram and canvas. |
|
The module metadata in the format of Spring Modulith’s |
|
A Mermaid diagram of all modules and an overview that renders on GitHub and GitLab. Quarkus extras. |
The directory is emptied first (quarkus.modulith.docs.clean). It must be a sub-directory of the build output: an absolute path, . or a path that leaves the build output with .. fails the build, so that cleaning can never delete sources. Copy the files elsewhere, for example to src/docs, in a later build step. Tests and dev mode write nothing, unless quarkus.modulith.docs.dev-mode=true. quarkus.modulith.docs.enabled=false skips the documentation.
The diagrams and canvases are configured with quarkus.modulith.docs.diagram. (style, dependency depth, dependency types, modules without relationships) and quarkus.modulith.docs.canvas. (groupings, internals, empty rows, Javadoc base URL). See Configuration reference.
Javadoc
Canvases show the Javadoc of modules, beans, events and listener methods when quarkus-modulith-apt runs during compilation. It writes META-INF/quarkus-modulith/javadoc.json, in the format of Spring Modulith’s SpringModulithProcessor:
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<annotationProcessorPaths>
<path>
<groupId>io.quarkiverse.modulith</groupId>
<artifactId>quarkus-modulith-apt</artifactId>
<version>${quarkus-modulith.version}</version>
</path>
</annotationProcessorPaths>
</configuration>
</plugin>
Components
Beans are grouped by role. The default groups are the jMolecules ones (CQRS, hexagonal, layered and onion architecture annotations, matched by name), then REST resources (@Path, @Route), services (jMolecules @Service, or *Service), repositories (Panache, Jakarta Data, jMolecules), event listeners, configuration mappings (@ConfigMapping, @ConfigProperty), scheduled jobs and messaging endpoints. quarkus.modulith.docs.canvas.groupings=spring uses Spring Modulith’s group names instead.
Configuration properties come from the @ConfigMapping interfaces of a module, with nested groups, @WithName, @WithDefault and the Javadoc of the methods, and from @ConfigProperty injection points. The build reads them from the Jandex index, and the Documenter of a plain test from the module types, which it loads with the context class loader without initializing them, so both canvases list the same properties.
The Documenter
Add quarkus-modulith-documenter with test scope and write the documentation from a test, as with Spring Modulith:
new Documenter(ApplicationModules.of(Application.class))
.writeModulesAsPlantUml()
.writeIndividualModulesAsPlantUml()
.writeModuleCanvases()
.writeAggregatingDocument();
Every method and option of Spring Modulith 2.1.2 exists:
-
writeDocumentation(),writeModulesAsPlantUml(),writeIndividualModulesAsPlantUml(),writeModuleAsPlantUml(module),writeModuleCanvases(),writeAggregatingDocument()andwriteModuleMetadata(), each also with options. -
DiagramOptions:withDependencyDepth,withExclusions,withComponentFilter,withTargetOnly,withTargetFileName,withColorSelector,withDefaultDisplayName,withStyle(DiagramStyle.C4,DiagramStyle.UML),withElementsWithoutRelationships,withSkinParam,withDependencyTypes. -
CanvasOptions:defaults,withoutDefaultGroupings,groupingBy,revealInternals,revealEmptyLines,withApiBase,withTargetFileName, withGrouping.of,nameMatching,implementing,subtypeOf,isAnnotatedWithand theJMoleculesGroupings,SpringGroupingsandQuarkusGroupings. -
DocumenterOptions(Spring Modulith’sDocumenter.Options):withOutputFolder,withoutClean. The default folder istarget/modulith-docs.withOutput(DocumentationOutput)writes the diagrams, canvases and aggregating document elsewhere; the module metadata ofwriteModuleMetadata(), whichwriteDocumentation()calls, still goes totarget/classes(build/resources/mainwithout apom.xml).
Kept from Spring Modulith:
-
A documenter builds its diagram model on the first diagram it writes. The display names of that call’s
withDefaultDisplayNameand the colors of itswithColorSelectorstay for every later diagram of the same documenter, so use a newDocumenterfor other names or colors. -
withTargetFileName("diagram-%s.puml")also names the diagram of all modules, unformatted: it is written todiagram-%s.puml, whichall-docs.adocincludes.
In a plain test the canvases have no "Scheduled jobs" and "Messaging endpoints" groups: the core model does not carry the method annotations those groups need. The build output has them.
The parity tests run Spring Modulith 2.1.2 and this documenter on the same fixtures and compare every file.
Differences from Spring Modulith
-
Options are top-level types:
Documenter.DiagramOptionsbecomesDiagramOptions,Documenter.OptionsbecomesDocumenterOptions, and so on. Component filters receive aDiagramComponent, groupings aModuleBean. -
The canvas row "Spring components" is called "Components", and the default groups have Quarkus names.
-
Spring Modulith orders diagram relationships and listener methods by hash codes, so their order changes between runs. Quarkus Modulith writes them in module order.
-
Writing the same diagram twice with one
DiagramOptionsinstance works; Spring Modulith rejects the second view. -
The module metadata goes to
META-INF/quarkus-modulith/application-modules.json. -
With
clean, on by default, the documenter refuses to empty a file system root, the working directory or one of its ancestors, a folder holding apom.xml,build.gradleorbuild.gradle.kts, and, inside the working directory, anything but a sub-folder oftargetorbuild.withOutputFolder("")fails. Spring Modulith empties any folder.
The /q/modulith endpoint
With an HTTP extension, /q/modulith returns the module model in the JSON format of Spring Modulith’s /actuator/modulith: per module the display name, base package, parent, nested modules, type, shared flag, allowed dependencies and dependencies with their types. The JSON is computed at build time. quarkus.modulith.endpoint.path changes the path.
The JSON maps the internals of the application, so the endpoint is served in dev and test mode only. A packaged application serves it only with quarkus.modulith.endpoint.enabled=true, as Spring Boot exposes /actuator/modulith over HTTP only when it is listed in management.endpoints.web.exposure.include. quarkus.modulith.endpoint.enabled=false removes it in every mode.
When you serve it in production, protect it. Either move it to the management interface, which listens on its own port (9000 by default) that you keep off the public network:
quarkus.modulith.endpoint.enabled=true
quarkus.management.enabled=true
or require authentication on the path with a security extension:
quarkus.modulith.endpoint.enabled=true
quarkus.http.auth.permission.modulith.paths=/q/modulith
quarkus.http.auth.permission.modulith.policy=authenticated
Dev UI
In dev mode the Modulith card has these pages:
- Modules
-
the modules with their base package, dependencies, allowed dependencies, named interfaces and events.
- Module graph
-
a force graph of the modules and their dependencies.
- Violations
-
the violations found by the last build. With the default
failmode the build stops instead, so this page matters inwarnmode. - Listeners
-
the
@ApplicationModuleListenermethods, their event types and delivery mode. - Initializers
-
the
ApplicationModuleInitializerbeans per module. - Incomplete publications
-
with an event publication store, the incomplete publications, with buttons to submit one or all of them again.
- Mermaid
-
the Mermaid source of the module diagram.