Maven Plugin and Documentation Generation

Relevant source files

• buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java

This page covers two related concerns: the structure and goals of the Spring Boot Maven plugin (spring-boot-maven-plugin), and the build-time tooling in buildSrc that generates AsciiDoc reference documentation from the plugin's compiled metadata. For information about the equivalent Gradle plugin, see 3.1. For how the generated documentation integrates into the broader reference docs pipeline, see 6.1.

---

Spring Boot Maven Plugin Overview

The spring-boot-maven-plugin lives at spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/. It provides Maven goals for packaging Spring Boot applications as executable JARs and WARs, building OCI images, and running applications during integration tests.

The plugin's goals (called "mojos" in Maven terminology) cover the full development lifecycle:

Goal	Primary Class	Purpose
repackage	RepackageMojo	Repackage a standard JAR/WAR into an executable fat JAR
run	RunMojo	Run the application in-process with Maven
start / stop	StartMojo / StopMojo	Fork the application for integration tests
build-image	BuildImageMojo	Build an OCI image using Cloud Native Buildpacks
build-info	BuildInfoMojo	Generate a build-info.properties file
process-aot	ProcessAotMojo	Run AOT processing ahead of native compilation
test-run	TestRunMojo	Run the application with the test classpath

The plugin's POM descriptor (plugin.xml) is generated by Maven during compilation and contains structured metadata for every mojo: its description, parameters, default values, user-configurable properties, and since-version markers. This descriptor is also the input to the documentation generation task described below.

---

The BuildImageMojo and Image Configuration

BuildImageMojo delegates most of its logic to the spring-boot-buildpack-platform library. Its configurable Image nested object lets users specify:

• The builder image name
• The target image name and tags
• Environment variables passed to buildpacks
• A list of explicitly named buildpacks
• Volume bindings and network mode
• Whether to publish the built image to a registry

The Image class is part of the org.springframework.boot.maven package, so all its fields appear as cross-referenced Javadoc links in the generated documentation (see the typeNameToJavadocLink logic described below).

---

Documentation Generation Architecture

A custom Gradle task, DocumentPluginGoals, reads the compiled plugin.xml and generates one AsciiDoc file per goal plus an overview.adoc index. This pipeline runs as part of the documentation build, not as part of the plugin build itself.

Documentation Generation Flow

Sources: buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java1-235

---

The PluginXmlParser Data Model

PluginXmlParser (in buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/PluginXmlParser.java) parses the Maven plugin descriptor XML into a three-level object hierarchy:

PluginXmlParser Data Model

Sources: buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java35-37

Key distinctions in Parameter:

• isEditable() — filters out read-only parameters; only editable parameters appear in the documentation tables
• isRequired() — splits parameters into separate "Required parameters" and "Optional parameters" sections
• getUserProperty() — if present, documents the -D system property a user can set on the command line
• getSince() — records the plugin version in which the parameter was introduced

---

DocumentPluginGoals Task

DocumentPluginGoals extends Gradle's DefaultTask. Its declared inputs and outputs participate in Gradle's incremental build cache.

Property	Annotation	Type	Role
pluginXml	@InputFile	RegularFileProperty	Path to plugin.xml
goalSections	@Input	MapProperty<String,String>	Maps each goal name to its AsciiDoc section ID
outputDir	@OutputDirectory	DirectoryProperty	Directory where .adoc files are written

The task entry point is documentPluginGoals() buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java58-64 It:

1. Parses plugin.xml into a Plugin object.
2. Calls writeOverview(plugin) to produce overview.adoc.
3. Iterates over plugin.getMojos() and calls documentMojo(plugin, mojo) for each.

Overview File

writeOverview buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java66-80 writes overview.adoc as an AsciiDoc two-column table:

[cols="1,3"]
|===
| Goal | Description

| xref:<section>#<section>.<goal>-goal[spring-boot:<goal>]
| <description>

...
|===

Each goal name is a cross-reference (xref:) that points to the goal's own section in the assembled documentation site.

Per-Goal File

documentMojo buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java82-123 writes <goal>.adoc with this structure:

1. Section anchor and heading (e.g., = \spring-boot:build-image``)
2. Plugin coordinates (groupId:artifactId:version)
3. Goal description
4. Required parameters table — only if non-empty, with columns: Name, Type, Default
5. Optional parameters table — only if non-empty, same columns
6. Parameter details section — one sub-section per editable parameter

Section ID Resolution

Every goal must appear in the goalSections map. The goalSectionId method buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java125-132 constructs an ID of the form:

<goalSection>.<goal>-goal

If a goal is missing from the map, the task throws IllegalStateException. This acts as a compile-time guard ensuring documentation coverage of all goals is intentionally maintained.

Type Linking

The typeNameToJavadocLink method buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java221-229 converts fully-qualified Java type names in parameter metadata into AsciiDoc cross-references:

Type package prefix	Generated link target
org.springframework.boot.maven	xref:maven-plugin:api/java/<path>.html[<short>]
org.springframework.boot	xref:api:java/<path>.html[<short>]
Any other	Plain short name (no link)

Nested classes (containing $) are converted to dot-separated paths for the Javadoc URL, and the short display name strips everything up to the last . or $.

---

Parameter Detail Format

Each parameter's detail block contains a structured table rendered in the final documentation:

Parameter Detail Layout

Sources: buildSrc/src/main/java/org/springframework/boot/build/mavenplugin/DocumentPluginGoals.java155-173

Optional rows (writeOptionalDetail) are always written — if the value is null, the cell is left empty. This keeps the table structure consistent even when a parameter has no default or user property.

---

Integration with the Documentation Build

The DocumentPluginGoals task is wired into the spring-boot-maven-plugin subproject's Gradle build. The generated .adoc files are consumed by the Antora documentation build in spring-boot-docs. The relationship is:

For the full documentation assembly pipeline including other generated content (configuration properties, auto-configuration classes, test slices), see 6.1.