Spring Boot Configuration Documentation – Two ways with IntelliJ Idea
IDE integrated options to assist the writing of configuration files.
In modern software development, the applications are driven by configuration.
If configurable properties are large in numbers, then it is difficult to remember the purpose, structure and type of each property. It becomes a necessity to invest in the documentation of these properties.
This article explores IDE integrated options to assist in writing Spring Boot YAML based configuration.
Originally, this article was published on DZone on 3 December, 2019.
Spring Configuration Processor¹
Spring Boot provides an out of box mechanism for configuration documentation: include a jar named
spring-boot-configuration-processor and trigger build.
⚙ How it works
- You trigger build.
- It scans
@ConfigurationPropertiesand constructs a JSON file which describes overall properties.
3. IDE intercepts generated file and helps you write configuration.
IntelliJ IDEA — Ultimate Edition detects the spring meta processor on the classpath and provides hints based upon metadata file generated.
However, there is no support on IntelliJ IDEA — Community Edition, Spring Tools 4 (Eclipse with Spring tools), Visual Code (with Spring tools).
YAML schema is newer, still evolving, and powerful option. In reality, YAML schema is written in JSON format² (strange!).
⚙ How it works
- You write schema by hand.
2. You create schema-mapping: mapping of files against schema governance.
3. IDE provides hints based upon schema provided to helps you write schema efficiently.
Now we have seen both ways, Let us compare:
Case #1: Static Properties
Consider configuration which accepts some fixed set of properties related to database connection.
Here is IDE performance on both style
The types of properties are not shown in suggestions in the case of YAML schema, yet it suggests the type while validating a property. With Spring Boot Configuration Metadata, Java exception message Type Mismatch is shown.
Case #2: Dynamic Properties
Let’s extend the previous case configuration. Consider the extension of configuration as below:
Based on the type; additional properties can be varied. Consider, two types of DB supported: Oracle and MySQL.
Oracle-specific properties if
oracle or MySQL-specific properties if
UML Class diagram for a possible solution
IDE is unable to distinguish Oracle properties with Mysql Properties in case of Spring Configuration Metadata. The generated spring metadata JSON file does not describe or command conditional nature of properties. Also, Spring Configuration metadata specification does not specify any conditional construct.
IDE is able to intercept the conditional properties in case of Yaml Schema.
💭 Wrapping Up
Spring Configuration Metadata programmer is equivalently good as YAML Schema for static configurable properties moreover it is automatically generated; however, this is supported by the paid edition of IntelliJ IDEA.
Yaml provides excellent conditional schema support which makes it powerful; however, writing such complex schema is not an easy task.
YAML schema is not limited to spring configuration files
bootstrap.yml but any YAML file. It enables a broad scope of applicability; it is a better choice for applications requiring external configuration.
What could be better ?
Spring developers should include conditional properties construct, or they can adopt YAML/ JSON schema, which would be future standard and would be understood by a broad audience (even with different language background!). Also, It would simplify IDE implementation.
- Spring Configuration Meta
- JSON Schema
- Polymorphic Spring Configuration https://stackoverflow.com/questions/53962547/polymorphic-configuration-properties-in-spring-boot
- Oracle Driver https://docs.oracle.com/cd/E13222_01/wls/docs81/jdbc_drivers/oracle.html