Spring Boot Configuration Documentation – Two ways with IntelliJ Idea

IDE integrated options to assist the writing of configuration files.

Puneet Sapra
Dec 4, 2019 · 4 min read

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.



Spring Configuration Processor¹

Spring Boot provides an out of box mechanism for configuration documentation: include a jar named and trigger build.

annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'

⚙ How it works

  1. You trigger build.
  2. It scans @ConfigurationProperties and constructs a JSON file which describes overall properties.
Generated File

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

YAML schema is newer, still evolving, and powerful option. In reality, YAML schema is written in ² (strange!).

At the time of writing, is released — tools like Visual Studio Code (with by Redhat), IntelliJ IDEA 2019.x support Draft#7.

⚙ How it works

  1. You write schema by hand.

2. You create schema-mapping: mapping of files against schema governance.

Mapping Definition | IntelliJ IDEA Community Edition

3. IDE provides hints based upon schema provided to helps you write schema efficiently.

Comparison

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.

Simple Set of properties

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 type is oracle or MySQL-specific properties if type is mysql.

UML Class diagram for a possible solution

Created with

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.

With Spring Configuration Metadata

IDE is able to intercept the conditional properties in case of Yaml Schema.

with Yaml Schema

💭 Wrapping Up

Photo by on

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 application.yml or 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.


References

  1. Spring Configuration Meta
  2. JSON Schema
  3. Polymorphic Spring Configuration
  4. Oracle Driver https://docs.oracle.com/cd/E13222_01/wls/docs81/jdbc_drivers/oracle.html

The Mighty Programmer

Software Design and Architecture Series | More at https://themightyprogrammer.dev

Puneet Sapra

Written by

Software Design Enthusiast. https://themightyprogrammer.dev/ https://www.linkedin.com/in/saprapuneet/

The Mighty Programmer

Software Design and Architecture Series | More at https://themightyprogrammer.dev

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade