One of my favorites low-key features of Spring Boot is the ability to map configuration properties from
into Java Beans using
@ConfigurationProperties annotation :
- It allows type-safe configuration binding
- It allows also easy validation using — with the standard JSR-380 specification.
spring-boot-configuration-processor, you can generate a configuration metadata in a JSON file,
which provides useful information on how to use the properties.
While this is mostly useful for your IDE to provide autocompletion and usage, in this post we are going to look at how to leverage this mechanism to document your custom properties in any format using jbang.
First let’s start by defining our custom application properties.
Let’s note a few things:
- our properties are included in a standard java bean class
- documentation is provided via our usual javadoc
- 💡tip: we define our custom properties in a given namespace. This is to ensure it does not clash with
other properties from spring core or a
@ConfigurationPropertiesScan), annotating your properties as a
@Componentas in this example, or by explicitly declaring it with
@EnableConfigurationProperties. Check the official documentation.
To generate a metadata files, let’s follow the instructions for maven, by adding the needed dependency in
pom.xml (configuration is provided for gradle users too).
Now to generate the configuration metadata, a standard
mvn compile command should generate our file in the build
It should look something like this :
The generated file contains our property name, value and description.
The configuration metadata format could also contain deprecation information, or even hints with possible values for a given property. You could even provide manual hints via an additional file. Be sure to check the official docs!.
Now that we have a
json file containing all the information we need, it would be nice to have a script that can:
- parse the
jsondata from one or many files
- aggregate it (in case of multiple files)
- export it to a file using a templating engine (to support any format:
This is exactly what I did using JBang, that I discovered not so long ago.
This time around I discovered that you can publish your scripts and easily share them with the world 🎉
The source code is available on github.
Using jbang’s implicit alias catalog you can call the script as easily as a single shell command.
This will download the script (you have to trust the source thought 😏), parse your current folder looking
META-INF/spring-configuration-metadata.json files and generates a markdown version using a default template.
Then it outputs the result to
Result should look like this (with your favorite markdown editor):
As any command line application, usage is provided via the
--metadata-location-folders: provides folders containing spring boot configuration metadata files (defaults to current folder)
--template: provides a
mustachetemplate file if you want to customize the output, instead of the default one. This could be useful if you want to export you documentation in another format (
--output: the exported filename
I should probably document what variables are available in case of providing a custom template, but hopefully the source code is a good starting point for the moment.
In conclusion, the article demonstrates the power of Spring Boot’s
@ConfigurationProperties combined with
We explored how to leverage this mechanism to document custom properties using JBang.
This approach could greatly simplify the documentation process by automating the extraction of property information and generating documentation in a desired format. It enhances the developer experience by providing autocomplete and usage information in IDEs and ensures that custom properties are well-documented and easily accessible to other team members.
Hope you found this useful, until next time 👋!