B.3 Generating your own meta-data using the annotation processor
You can easily generate your own configuration meta-data file from items annotated with @ConfigurationProperties
by using the spring-boot-configuration-processor
jar. The jar includes a Java annotation processor which is invoked as your project is compiled. To use the processor, simply include spring-boot-configuration-processor
as an optional dependency, for example with Maven you would add:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency>
With Gradle, you can use the propdeps-plugin and specify:
dependencies { optional "org.springframework.boot:spring-boot-configuration-processor" } compileJava.dependsOn(processResources) }
Note | |
---|---|
You need to add compileJava.dependsOn(processResources) to your build to ensure that resources are processed before code is compiled. Without this directive any additional-spring-configuration-metadata.json files will not be processed. |
The processor will pick up both classes and methods that are annotated with @ConfigurationProperties
. The Javadoc for field values within configuration classes will be used to populate the description
attribute.
Note | |
---|---|
You should only use simple text with @ConfigurationProperties field Javadoc since they are not processed before being added to the JSON. |
Properties are discovered via the presence of standard getters and setters with special handling for collection types (that will be detected even if only a getter is present). The annotation processor also supports the use of the @Data
, @Getter
and @Setter
lombok annotations.
Note | |
---|---|
If you are using AspectJ in your project, you need to make sure that the annotation processor only runs once. There are several ways to do this: with Maven, you can configure the maven-apt-plugin explicitly and add the dependency to the annotation processor only there. You could also let the AspectJ plugin run all the processing and disable annotation processing in the maven-compiler-plugin configuration: |
B.3.1 Nested properties
The annotation processor will automatically consider inner classes as nested properties. For example, the following class:
_@ConfigurationProperties(prefix="server")_ public class ServerProperties { private String name; private Host host; // ... getter and setters private static class Host { private String ip; private int port; // ... getter and setters } }
Will produce meta-data information for server.name
, server.host.ip
and server.host.port
properties. You can use the @NestedConfigurationProperty
annotation on a field to indicate that a regular (non-inner) class should be treated as if it were nested.
B.3.2 Adding additional meta-data
Spring Boot’s configuration file handling is quite flexible; and it is often the case that properties may exist that are not bound to a @ConfigurationProperties
bean. You may also need to tune some attributes of an existing key. To support such cases and allow you to provide custom "hints", the annotation processor will automatically merge items from META-INF/additional-spring-configuration-metadata.json
into the main meta-data file.
If you refer to a property that has been detected automatically, the description, default value and deprecation information are overridden if specified. If the manual property declaration is not identified in the current module, it is added as a brand new property.
The format of the additional-spring-configuration-metadata.json
file is exactly the same as the regular spring-configuration-metadata.json
. The additional properties file is optional, if you don’t have any additional properties, simply don’t add it.