Maven Plugin

If you are having a Maven project where you would like to use the tool, then this documentation will guide you through all the steps you need to set it up, you can use it for a single module Maven project or a multi-module Maven project, both are supported.

📎	The plugin is built with Java 11 and Maven 3.8.1 API, make sure requirements are met.

⚠️	The multi-module setup will need a "small" trick/hack to achieve the things we want.

Table of Contents

Setup
- Single module
- Multi-module
Available goals and configuration
- Configuration

Setup

Single module

In this case the story is relatively simple, you have to only insert the following code snippet to your pom.xml and after that you can use it immediately.

The plugin is having multiple goals at this moment, please check out the documentation and customization for those.

Spring’s annotation processor will kick in the compile phase, and because of that the plugin must be linked after that lifecycle, for example the process-classes.

pom.xml

 <build>
        <plugins>
            ...
            <plugin>
                <groupId>org.rodnansol</groupId>
                <artifactId>spring-configuration-property-documenter-maven-plugin</artifactId>
                <version>latest-version</version>
                <executions>
                    <execution>
                        <id>generate-adoc</id>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>generate-property-document</goal>
                        </goals>
                        <configuration>
                            <type>ADOC</type>
                        </configuration>
                    </execution>
                    <execution>
                        <id>generate-markdown</id>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>generate-property-document</goal>
                        </goals>
                        <configuration>
                            <type>MARKDOWN</type>
                        </configuration>
                    </execution>
                    <execution>
                        <id>generate-html</id>
                        <phase>process-classes</phase>
                        <goals>
                            <goal>generate-property-document</goal>
                        </goals>
                        <configuration>
                            <type>HTML</type>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        ...
        </plugins>
    </build>

In this example 3 files are going to be created with different extensions (Markdown, AsciiDoc, HTML).

Multi-module

Bigger projects are going to be containing multiple Maven modules and the plugin is also prepared for those cases as well, we can generate the document for each module, and we are going to be able to aggregate them. There are two supported options right now.

For these cases we have to introduce a new module that will contain all the other modules as its dependencies, with this "trick" we can ensure that the plugin will be invoked at the end of the Maven build and all the required resources (the spring-configuration-metadata.json files) will be already generated (without those it will be really hard to generate the final docucment).

Check the diagram below:

In the multi-module-docs module we have to configure the plugin:

pom.xml

 <build>
        <plugins>
            <plugin>
                <groupId>org.rodnansol</groupId>
                <artifactId>spring-configuration-property-documenter-maven-plugin</artifactId>
                <version>latest-version</version>
                <executions>
                    <execution>
                        <id>aggregate-docs-markdown</id>
                        <goals>
                            <goal>generate-and-aggregate-documents</goal>
                        </goals>
                        <phase>package</phase>
                        <configuration>
                            <type>MARKDOWN</type>
                            <inputs>
                                <input>
                                    <name>Multi Module A</name>
                                    <description>Multi Module A properties with a folder input</description>
                                    <input>../multi-module-a</input>
                                </input>
                                <input>
                                    <name>Multi Module B</name>
                                    <description>Multi Module B properties with a jar file input</description>
                                    <input>../multi-module-b/target/multi-module-b-999-SNAPSHOT.jar</input>
                                </input>
                                <input>
                                    <name>Multi Module C</name>
                                    <description>Multi Module C properties with a specific file input</description>
                                    <input>../multi-module-c/target/classes/META-INF/spring-configuration-metadata.json</input>
                                </input>
                            </inputs>
                            <outputFile>target/aggregated-md.md</outputFile>
                        </configuration>
                    </execution>
                    <execution>
                        <id>aggregate-docs-markdown-adoc</id>
                        <goals>
                            <goal>generate-and-aggregate-documents</goal>
                        </goals>
                        <phase>package</phase>
                        <configuration>
                            <type>ADOC</type>
                            <inputs>
                                <input>
                                    <name>Multi Module A</name>
                                    <description>Multi Module A properties with a folder input</description>
                                    <input>../multi-module-a</input>
                                </input>
                                <input>
                                    <name>Multi Module B</name>
                                    <description>Multi Module B properties with a jar file input</description>
                                    <input>../multi-module-b/target/multi-module-b-999-SNAPSHOT.jar</input>
                                </input>
                                <input>
                                    <name>Multi Module C</name>
                                    <description>Multi Module C properties with a specific file input</description>
                                    <input>../multi-module-c/target/classes/META-INF/spring-configuration-metadata.json</input>
                                </input>
                            </inputs>
                            <outputFile>target/aggregated-adoc.adoc</outputFile>
                        </configuration>
                    </execution>
                    <execution>
                        <id>aggregate-docs-markdown-html</id>
                        <goals>
                            <goal>generate-and-aggregate-documents</goal>
                        </goals>
                        <phase>package</phase>
                        <configuration>
                            <type>HTML</type>
                            <inputs>
                                <input>
                                    <name>Multi Module A</name>
                                    <description>Multi Module A properties with a folder input</description>
                                    <input>../multi-module-a</input>
                                </input>
                                <input>
                                    <name>Multi Module B</name>
                                    <description>Multi Module B properties with a jar file input</description>
                                    <input>../multi-module-b/target/multi-module-b-999-SNAPSHOT.jar</input>
                                </input>
                                <input>
                                    <name>Multi Module C</name>
                                    <description>Multi Module C properties with a specific file input</description>
                                    <input>../multi-module-c/target/classes/META-INF/spring-configuration-metadata.json</input>
                                </input>
                            </inputs>
                            <outputFile>target/aggregated-html.html</outputFile>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

The generate-and-aggregate-documents goal is not linked to any lifecycle, but it must be run after all the other modules have been built. We use the package lifecycle here, but other can be used as well, the dependency association will make sure that this module can not be built until the other dependencies are not available/built.

As we can see in the input tags we can define an input field that can be:

a specific spring-configuration-metadata.json file
a directory (that must contain the spring-configuration-metadata.json in the children directories)
a jar file (that must contain the spring-configuration-metadata.json in the META-INF directory)

Available goals and configuration

Goal	Description
`generate-property-document`	This goal reads the `spring-configuration-metadata.json` file from any given source (input file, directory or JAR file) and generates a single document for the given module. It is good to document a single application or a single module.
`generate-and-aggregate-documents`	This goal reads all the given `spring-configuration-metadata.json` files from the given/specified sources and it will be generating one single document that will contain all documentation created by the given sources. This goal is good for a multi module setup, it is able to read multiple files and aggregate them.
`aggregate-documents`	This goal reads all the given files and it will aggregates them into one big file. It is good if you have multiple different template based documentation and you would like to aggregate them into one. This is not going to generate documents only aggregate the given ones, this has a different purpose than the `generate-and-aggregate-documents`.

Configuration

`generate-property-document`

Configuration

Parameter name	Description	Mandatory	Default value	Since
name	Main header’s name	No (it will be inferred if not specified from the default value)	`${project.name}`	0.1.0
description	Description about the module that will be generated into the document	No (it will be inferred if not specified from the default value)	`${project.description}`	0.1.0
template	Template to be used during the generation, if not specified the default templates are going to be used, (by default the file’s name must end with `.hbs` but in this property the `.hbs` extension must be omitted) - For more information check the template customization section	No		0.1.0
type	The type of the document, basically the extension. If the `template` is not being specified the default template will be resolved based on this value.	No	MARKDOWN	0.1.0
markdownCustomization	Markdown customization configurations. For more information check the class or this.	No	`org.rodnansol.core.generator .template.customization .MarkdownTemplateCustomization` class.	0.2.0
asciiDocCustomization	AsciiDoc customization configurations. For more information check the class or this.	No	`org.rodnansol.core.generator .template.customization .AsciiDocTemplateCustomization` class.	0.2.0
htmlCustomization	HTML customization configurations. For more information check the class or this.	No	`org.rodnansol.core.generator .template.customization .HtmlTemplateCustomization` class.	0.2.0
xmlCustomization	XML customization configurations. For more information check the class or this.	No	`org.rodnansol.core.generator .template.customization .XmlTemplateCustomization` class.	0.2.0
metadataInput	Path to the metadata input: - A path to JSON file for example: target/classes/META-INF/spring-configuration-metadata.json - A directory that contains the file - A jar/zip file that contains the file within the following entry META-INF/spring-configuration-metadata.json	No	target/classes/META-INF/spring-configuration-metadata.json	0.1.0
templateCompilerName	Custom template compiler’s fully qualified name	No	`org.rodnansol.core .generator.template .HandlebarsTemplateCompiler`	0.2.0
outputFile	The output file’s full path	Yes		0.1.0
failOnError	If the Maven build should fail in case the document generation fails.	No	false	0.1.0
excludedGroups	List of groups that should be excluded from the final document	No	Empty list - Everything will be included	0.4.0
includedGroups	List of groups that should be included int the final document	No	Empty list - Everything will be included	0.4.0
excludedProperties	List of properties that should be excluded from the final document	No	Empty list - Everything will be included	0.4.0
includedProperties	List of properties that should be included int the final document	No	Empty list - Everything will be included	0.4.0
failOnMissingInput	Defines if the build should fail if the input file is missing/not existing.	Yes		0.7.0

`generate-and-aggregate-documents`

Configuration

Parameter name	Description	Mandatory	Default value	Since
name	Main header’s name	No (it will be inferred if not specified from the default value)	`${project.name}`	0.1.0
description	Description about the module that will be generated into the document	No (it will be inferred if not specified from the default value)	`${project.description}`	0.1.0
type	The type of the document, basically the extension. If the `template` is not being specified the default template will be resolved based on this value.	No	MARKDOWN	0.1.0
markdownCustomization	Markdown customization configurations. For more information check the class or this.	No	`org.rodnansol .core.generator .template.customization .MarkdownTemplateCustomization` class.	0.2.0
asciiDocCustomization	AsciiDoc customization configurations. For more information check the class or this.	No	`org.rodnansol .core.generator .template.customization .AsciiDocTemplateCustomization` class.	0.2.0
htmlCustomization	HTML customization configurations. For more information check the class or this.	No	`org.rodnansol .core.generator .template.customization .HtmlTemplateCustomization` class.	0.2.0
xmlCustomization	XML customization configurations. For more information check the class or this.	No	`org.rodnansol .core.generator .template.customization .XmlTemplateCustomization` class.	0.2.0
inputs	Multiple input file - Type: AggregationMojoInput below	No		0.1.0
outputFile	The output file’s full path	Yes		0.1.0
templateCompilerName	Custom template compiler’s fully qualified name - For more information check the template customization section	No	`org.rodnansol.core .generator.template .HandlebarsTemplateCompiler`	0.2.0
headerTemplate	Custom header template file’s path (by default the file’s name must end with `.hbs` but in this property the `.hbs` extension must be omitted) - For more information check the template customization section	No		0.2.1
contentTemplate	Custom content template file’s path (by default the file’s name must end with `.hbs` but in this property the `.hbs` extension must be omitted) - For more information check the template customization section	No		0.2.1
footerTemplate	Custom footer template file’s path (by default the file’s name must end with `.hbs` but in this property the `.hbs` extension must be omitted) - For more information check the template customization section	No		0.2.1
failOnMissingInput	Defines if the build should fail if any of the input files are missing/not existing.	Yes		0.7.0

Table 1. org.rodnansol.maven.AggregationMojoInput

Parameter name Description Mandatory Since

name

Name of the module

Yes

0.1.0

description

Description of the module

No

0.1.0

input

Input file or path

- A path to JSON file for example:

target/classes/META-INF/spring-configuration-metadata.json

- A directory that contains the file

- A jar/zip file that contains the file within the following entry:

META-INF/spring-configuration-metadata.json

Yes

0.1.0

`aggregate-documents`

⚠️	Exprimental goal, no documentation yet.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

maven-plugin.adoc

maven-plugin.adoc

Maven Plugin

Setup

Single module

Multi-module

Available goals and configuration

Configuration

`generate-property-document`

`generate-and-aggregate-documents`

`aggregate-documents`

Files

maven-plugin.adoc

Latest commit

History

maven-plugin.adoc

File metadata and controls

Maven Plugin

Setup

Single module

Multi-module

Available goals and configuration

Configuration

generate-property-document

generate-and-aggregate-documents

aggregate-documents

`generate-property-document`

`generate-and-aggregate-documents`

`aggregate-documents`