spring-configuration-aggregator-maven-plugin

Spring Configuration Extensions: Aggregator Maven Plugin

Maven plugin that aggregates all Spring configuration metadata files of the project dependencies into a single one.

It generates a aggregated-spring-configuration-metadata.json, similar to the Configuration Metadata format defined by Spring Boot.

Additionally, this plugin allows to generate customizable reports in json, html or pdf formats.

Generated metadata

For every dependency, the plugin will check if one of the following files is present:

• META-INF/spring-configuration-metadata.json
• META-INF/additional-spring-configuration-metadata.json

These files are usually generated by the Spring Boot Configuration Processor.

Note: if you are still using @Value annotations, you can use following processor to handle them: Spring Value Annotation Processor

All found files will then be merged into a single file, with following attributes:

• the name of the configuration property used
• the type of the attribute
• the description taken from the JavaDoc defined on the attribute (if any)
• the defaultValue specified in the annotation, or in the properties file (if any)
• the profiles maps all defined values per Spring profile
• the sourceTypes lists all references to this property:
  • the groupId, the group id of the dependency
  • the artifactId, the artifact id of the dependency
  • the sourceType, the class referencing this property

Usage

You can simply add the project to the build plugin section.

<plugin>
    <groupId>com.github.egoettelmann</groupId>
    <artifactId>spring-configuration-aggregator-maven-plugin</artifactId>
    <version>0.2.1</version>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

After executing mvn clean package, you can find the aggregated-spring-configuration-metadata.json file under target/classes/META-INF/.

Configuration

The plugin can be configured through following properties:

Property	Type	Description
skip	boolean	Allows to skip the execution. Default: false.
failOnError	boolean	Specifies if errors during the aggregation should make the build fail. Default: true.
aggregationFile	String	The output file. Default: ${project.build.outputDirectory}/META-INF/aggregated-spring-configuration-metadata.json
includeDependencies	List<DependencyMatcher>	Specifies a list of dependencies to include for aggregation.
excludeDependencies	List<DependencyMatcher>	Specifies a list of dependencies to exclude from aggregation.
propertiesFiles	List<PropertiesFile>	Specifies a list of properties files to parse for default values.
additionalMetadataFiles	List<MetadataFile>	Specifies a list of json files to retrieve additional configuration metadata from.
profiles	String	Comma separated list of Spring profiles to include values for.
outputReports	List<OutputReport>	Specifies a list of reports to generate.
changes	ChangesOptions	Options for computing configuration changes.

The DependencyMatcher type is defined with following properties:

Property	Type	Description
groupId	String	The groupId to filter on.
artifactId	String	The artifactId to filter on.
scope	String	The scope to filter on.

The PropertiesFile type is a string defining a file path. To load additional default values (not defined in annotations), configuration files can be defined here. Supported file types are: .properties, .yml and .yaml. By default, following files are loaded:

• ${project.baseDir}/src/main/resources/application.yml
• ${project.baseDir}/src/main/resources/application.yaml
• ${project.baseDir}/src/main/resources/application.properties

The MetadataFile type is a string defining a file path. In any case, following files are looked up:

• /META-INF/spring-configuration-metadata.json
• /META-INF/additional-spring-configuration-metadata.json

The OutputReport type is defined with following properties:

Property	Type	Description
type	String	The type of the report: json, html or pdf
templateFile	String	The path to the template to use (for html/pdf )
outputFile	String	The path to the file to generate.

For detailed explanations regarding the configuration of OutputReport, see the report goal below.

The ChangesOptions type is defined with following properties:

Property	Type	Description
skip	boolean	Allows to skip the changes computation.
baseVersion	String	The version to compute the changes against.
baseFilePath	String	The path to a aggregated property metadata file to compute changes against.

Additional goal: report

In addition to the main goal, you can use the report goal to generate custom output files, in various formats.

This can be useful, for example if you want to include the various configuration options of your project in its documentation.

Before generating the output files, this goal consolidates all aggregated properties. As each configuration property can appear multiple times (the metadata file has an entry for each reference), the plugin merges all entries referencing the same property.

Following types of reports are available:

• json
  • by default the output goes to: ${project.build.directory}/${project.artifactId}-${project.version}-configurations.json
  • the option templateFile is ignored for this type
  • this report is generated by default for the report goal
• html
  • the default templateFile can be found here: default.ftl
  • the template is rendered with Freemarker
  • the default outputFile is: ${project.build.directory}/apidocs/configurations.html
  • it can be easily included in your Javadoc (check the samples section)
• pdf
  • the default templateFile is the same as for html
  • the template is rendered as HTML first with Freemarker
  • the resulting HTML is then rendered with: Open HTML to PDF
  • the default outputFile is: ${project.build.directory}/${project.artifactId}-${project.version}-configurations.pdf

Check the below samples section to view the usage

Samples

Some examples configurations are given below.

For full working examples have a look into spring-configuration-extensions-samples.

Sample 1

Simple aggregation, with following additional options:

• ignoring errors, to prevent that the build fails
• excluding configuration properties defined in test scope dependencies
• excluding all Springboot related configuration properties

<plugin>
    <groupId>com.github.egoettelmann</groupId>
    <artifactId>spring-configuration-aggregator-maven-plugin</artifactId>
    <version>0.2.1</version>
    <configuration>
        <!-- Ignores errors -->
        <failOnError>false</failOnError>
        <excludeDependencies>
            <!-- Excludes all metadata defined in 'test' scope dependencies -->
            <dependencyMatcher>
                <scope>test</scope>
            </dependencyMatcher>
            <!-- Excludes all metadata defined in Spring Boot dependencies -->
            <dependencyMatcher>
                <groupId>org.springframework.boot</groupId>
            </dependencyMatcher>
        </excludeDependencies>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Sample 2

Simple aggregation, by only including properties from:

• the current project
• and dependencies with the same groupId of the current project

<plugin>
    <groupId>com.github.egoettelmann</groupId>
    <artifactId>spring-configuration-aggregator-maven-plugin</artifactId>
    <version>0.2.1</version>
    <configuration>
        <includeDependencies>
            <!-- Includes only metadata defined in dependencies with same 'groupId' as current project -->
            <dependencyMatcher>
                <groupId>${project.groupId}</groupId>
            </dependencyMatcher>
        </includeDependencies>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Sample 3

Aggregation and reporting of all configuration properties.

<plugin>
    <groupId>com.github.egoettelmann</groupId>
    <artifactId>spring-configuration-aggregator-maven-plugin</artifactId>
    <version>0.2.1</version>
    <configuration>
        <outputReports>
            <!-- Generating default JSON report -->
            <outputReport>
                <type>json</type>
            </outputReport>
            <!-- Generating default HTML report -->
            <outputReport>
                <type>html</type>
            </outputReport>
            <!-- Generating PDF with template located in resources -->
            <outputReport>
                <type>pdf</type>
                <templateFile>${basedir}/src/main/resources/config.template.ftl</templateFile>
            </outputReport>
        </outputReports>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>
                <goal>report</goal>
            </goals>
        </execution>
    </executions>
</plugin>

Sample 4

Simple aggregation, that declares custom configuration files to load default values from:

• the default application.yml file (as loaded by SpringBoot)
• the additional custom-config.properties file

<plugin>
    <groupId>com.github.egoettelmann</groupId>
    <artifactId>spring-configuration-aggregator-maven-plugin</artifactId>
    <version>0.2.1</version>
    <configuration>
        <!-- Loading default values from custom configuration file -->        
        <propertiesFiles>
            <propertiesFile>${project.basedir}/src/main/resources/application.yml</propertiesFile>
            <propertiesFile>${project.basedir}/src/main/resources/custom-config.properties</propertiesFile>
        </propertiesFiles>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>aggregate</goal>
            </goals>
        </execution>
    </executions>
</plugin>