Problems
Have you ever felt that you have no proper way to oversee a project because it is having a lot of customizable properties, but they are not documented, and you do not know where to start a new feature or bugfix?
Have you ever felt like you are having too much services, and you do not know how to customize them externally?
Have you ever wondered is there any way to document your application's properties that you are having in your project?
If for any question your answer is YES then you are at the best place.
Spring Configuration Property Documenter
This tool lets you generate informative and useful documentations about the classes annotated with the @ConfigurationProperties
in your project.
But how?
It is easy, if you are working with Spring Boot, you first need a dependency on your classpath during build time, it is annotation processor that will read your classes and generates a metadata file based on the annotation configuration classes.
In case of Maven, you should add the following dependency:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
After a mvn package
the following file should appear in your target
folder's META-INF
folder: spring-configuration-metadata.json
.
It is a simple JSON file, but it contains information about your configuration properties.
Let's see an example:
@Component
@ConfigurationProperties(prefix = "this.is.my")
class MyProperties {
/**
* This is my variable.
*/
private String variable;
@Deprecated(since = "Since you are a pilot")
private String anotherVariable = "with default value";
/**
* A duration.
*/
private Duration duration = Duration.ofDays(2);
private Instant instant = Instant.ofEpochSecond(123);
private LocalDate date = LocalDate.of(1995, 10, 20);
private LocalDateTime dateTime = LocalDateTime.of(1995, 10, 20, 0, 1, 2, 3);
// Getters & Setters
@DeprecatedConfigurationProperty(reason = "Because it is deprecated", replacement = "instant")
public Duration getDuration() {
return duration;
}
}
Generated spring-configuration-metadata.json
file:
{
"groups": [
{
"name": "this.is.my",
"type": "org.rodnansol.MyProperties",
"sourceType": "org.rodnansol.MyProperties"
}
],
"properties": [
{
"name": "this.is.my.date",
"type": "java.time.LocalDate",
"sourceType": "org.rodnansol.MyProperties"
},
{
"name": "this.is.my.date-time",
"type": "java.time.LocalDateTime",
"sourceType": "org.rodnansol.MyProperties"
},
{
"name": "this.is.my.instant",
"type": "java.time.Instant",
"sourceType": "org.rodnansol.MyProperties"
},
{
"name": "this.is.my.variable",
"type": "java.lang.String",
"description": "This is my variable.",
"sourceType": "org.rodnansol.MyProperties"
},
{
"name": "this.is.my.another-variable",
"type": "java.lang.String",
"sourceType": "org.rodnansol.MyProperties",
"deprecated": true,
"deprecation": {}
},
{
"name": "this.is.my.duration",
"type": "java.time.Duration",
"description": "A duration.",
"sourceType": "org.rodnansol.MyProperties",
"deprecated": true,
"deprecation": {
"reason": "Because it is deprecated",
"replacement": "instant"
}
}
],
"hints": []
}
Okay, but what's next?
We built you a tool that can use this JSON file and can generate a documentation from it in the following formats:
- Markdown
- AsciiDoc
- HTML
- XML - in case of an XSLT transformation and with XSD support
- You name it
You can find it here.
What can it do?
Reading one or multiple metadata files
After it reads your metadata JSON file, a document will be created in the specified format.
Multiple JSON metadata files can be specified before the process, multi-module projects can also utilize it to have only one document where all the properties are available from the different modules.
If the metadata file is in a JAR file, it is not a problem, the tool can read it from the JAR file.
Aggregating more metadata files
If you are working in a multi-module environment, you may have multiple metadata files, but you do not have to worry, single documentations and aggregated documentations also can be produced.
Default templates and customization
The tool provides you a default template that is written with Handlebars, but it is also prepared to support custom templates as well.
By default, the Handlebars templating engine is supported, but you have the ability to use your own templating engine, but you have to write an extension for it.
Check out the documentation here.
Excluding and including groups and properties
As the tool lets you read and use metadata files from JAR files as well, you are able to extract information from the official Spring Boot JARs and you can put this into your final documenatation.
Sometimes these files are big and you may want to select specific groups and/or keys to be rendered or not rendered into the final output.
Exclusion and inclusion lists are also supported.
Please check the following samples here.
How to use the tool?
The core functionalities are built with Java 11 and these functionalities are available through:
Maven usage
Just add the following plugin to your pom.xml
and you are ready to go.
<plugin>
<groupId>org.rodnansol</groupId>
<artifactId>spring-configuration-property-documenter-maven-plugin</artifactId>
<version>${final-version}</version>
<executions>
<execution>
<id>generate-adoc</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>ADOC</type>
</configuration>
</execution>
</executions>
</plugin>
Check the available Maven goals here.
Template customization
The templates can be customized if the default one is not fitting your requirements, please read the docs about that here.
Checkout the samples & docs
Feel free to check out the samples and documentation because it will give a wider knowledge about the how-tos.
Are you using Spring Boot with Quarkus?
If yes, do not worry, we got you covered, check out this sample.
Top comments (0)