Master Spring Boot Configuration Processor to Generate Accurate Metadata

1. Overview

When writing a Spring Boot application, mapping configuration properties to a Java bean is useful, but how should those properties be documented? This tutorial explores the Spring Boot Configuration Processor and the associated JSON metadata file that records each property's meaning, constraints, and more.

2. Configuration Metadata

Most applications need to be configurable, yet developers often lack insight into what each configuration parameter does, its default value, or whether it is deprecated. Spring Boot generates a JSON metadata file that provides useful information about how to use each property. The metadata is a descriptive file containing the necessary information for interacting with configuration properties.

The benefit of this file is that IDEs can read it, offering auto‑completion and other configuration hints.

3. Dependency

To generate the metadata we add the spring-boot-configuration-processor as an optional dependency.

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <version>2.1.7.RELEASE</version>
    <optional>true</optional>
</dependency>

This dependency provides the annotation processor that runs during compilation.

Marking the dependency as optional prevents @ConfigurationProperties from being applied to other modules.

4. Configuration Property Example

We define a Java bean to hold some properties:

@Configuration
@ConfigurationProperties(prefix = "database")
public class DatabaseProperties {

    public static class Server {
        private String ip;
        private int port;
        // standard getters and setters
    }

    private String username;
    private String password;
    private Server server;
    // standard getters and setters
}

We then add the corresponding entries to databaseproperties-test.properties:

#Simple Properties
database.username=baeldung
database.password=password

A test verifies that the simple properties are bound correctly:

@RunWith(SpringRunner.class)
@SpringBootTest(classes = AnnotationProcessorApplication.class)
@TestPropertySource("classpath:databaseproperties-test.properties")
public class DatabasePropertiesIntegrationTest {

    @Autowired
    private DatabaseProperties databaseProperties;

    @Test
    public void whenSimplePropertyQueriedThenReturnsPropertyValue() throws Exception {
        Assert.assertEquals("Incorrectly bound Username property", "baeldung", databaseProperties.getUsername());
        Assert.assertEquals("Incorrectly bound Password property", "password", databaseProperties.getPassword());
    }
}

We also add nested properties for database.server.ip and database.server.port and test them:

@Test
public void whenNestedPropertyQueriedThenReturnsPropertyValue() throws Exception {
    Assert.assertEquals("Incorrectly bound Server IP nested property", "127.0.0.1", databaseProperties.getServer().getIp());
    Assert.assertEquals("Incorrectly bound Server Port nested property", 3306, databaseProperties.getServer().getPort());
}

5. Generate Configuration Metadata

After compilation the processor creates target/classes/META-INF/spring-configuration-metadata.json:

{
  "groups": [
    {
      "name": "database",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server",
      "type": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties",
      "sourceMethod": "getServer()"
    }
  ],
  "properties": [
    {
      "name": "database.password",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    },
    {
      "name": "database.server.ip",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server"
    },
    {
      "name": "database.server.port",
      "type": "java.lang.Integer",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties$Server",
      "defaultValue": 0
    },
    {
      "name": "database.username",
      "type": "java.lang.String",
      "sourceType": "com.baeldung.autoconfiguration.annotationprocessor.DatabaseProperties"
    }
  ],
  "hints": []
}

5.1 Additional Information

We add Javadoc to the Server class and set a default value and validation annotations for database.server.port:

public static class Server {

    /**
     * The IP of the database server
     */
    private String ip;

    /**
     * The Port of the database server.
     * The Default value is 443.
     * The allowed values are in the range 400‑800.
     */
    @Min(400)
    @Max(800)
    private int port = 443;

    // standard getters and setters
}

The updated spring-configuration-metadata.json now includes descriptions, default values, and validation ranges for the port property.

5.2 Understanding the Metadata Format

Groups are high‑level entries used to group related properties; they do not hold values themselves. In our example we have a database group and a nested database.server group.

Properties represent individual configuration items that can be set in *.properties or *.yml files. They may include default values and validation constraints.

Hints provide additional guidance for users, such as allowed values, which IDEs can use for auto‑completion.

6. Summary

This article introduced the Spring Boot Configuration Processor and demonstrated how it generates configuration metadata that simplifies interaction with configuration parameters. We showed a complete example, explained the JSON format, and highlighted the benefits of IDE auto‑completion support.