-
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.
The Spring Framework is a really powerful tool that lets you build simple and complex application with Java. Developers have been using it as their main framework to build applications, and during any software development developers tend to make their solutions future-proof and highly customizable.
To make sure these goals could be achieved proper requirements and documents are required for the team and the software. As the software is being built and new features are being implemented and as the codebase is growing, developers tend to make shortcuts, and they stop writing documentations, the requirements are getting weaker and the quality of the software is getting worse.
Developers like to automatize most of their "boring" tasks and creating documentation is a good candidate for this one, if the code itself contains enough information to make it as the "official" documentation, then why shouldn’t we utilize tools that achieve these goals?
The Spring Framework ships an annotation processing library that creates metadata from the classes thar are annotation with the @ConfigurationProperties annotation. This library is called spring-boot-configuration-processor and you can read more about it here: Configuration Metadata.
After your application has this dependency during build time the annotation processor will kick in and a so called spring-configuration-metadata.json file will be created, that will represent your @ConfigurationProperties annotated classes in a JSON file format, these are metadata about your classes.
An example class and its metadata
@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;
}
}{
"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": []
}This tool is going to read and process this metadata file, and it is able to generate shiny "documentations" in different formats.
This tool will let you create:
-
Markdown
-
AsciiDoc
-
HTML
-
XML
-
More to come…
styled documents about your configuration properties.
The tool is using Handlebars as the templating engine, if you would like to create custom templates check the Template customization section.
Check out the samples folder for the different samples.
|
💡
|
If you are using Spring with Quarkus, you can use this tool as well, please check out the Quarkus example in the samples folder. |
mvn clean package \
org.rodnansol:spring-configuration-property-documenter-maven-plugin:0.7.0:generate-property-document \
-Dtype=ADOCAn Asciidoc based property documentation should be available in your target/property-docs folder.
<plugin>
<groupId>org.rodnansol</groupId>
<artifactId>spring-configuration-property-documenter-maven-plugin</artifactId>
<version>0.7.0</version>
<executions>
<execution>
<id>generate-adoc-without-deprecation-and-type</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>ADOC</type>
</configuration>
</execution>
</executions>
</plugin>|
📎
|
Don’t worry, we have a Gradle plugin as well, check it out here. |
The tool has been built with Java and there are different entry points to it, but to be able to use it there are a few requirements:
-
Java 11
-
In case of a Maven project you need Maven 3 at least.
The project is currently having the following modules:
This Maven module contains the "core" codebase for the whole project, other modules are just entry points to this core module.
This Maven module is a Maven plugin implementation, please check the Maven plugin part for the available goals and configuration.
If you are not willing to use the Maven/Gradle plugin (that is coming soon), and you are familiar with JBang you can use this module where a PropertyDocumenter script is resides, to have a new entry point to the tool. Please read the JBang for more information.
This Maven module is a Gradle plugin implementation, please check the Gradle part for the available goals and configuration.
As said before the tool can be executed by multiple tools, by far probably the most convenient is going to be the Maven and Gradle plugin, but we offer another approach with JBang.
The project requires at least Java 11, if sdkman is installed on your machine sdk e command could be used in the terminal to set up the required Java version.
-
To build the project just run:
mvn verify -
If you want to build the samples run:
mvn installand thenmvn package -f samples/pom.xml
The project contains a .editorconfig file, and it should be utilized as well.
During build time Checkstyle checks the conventions.
The commit messages are based on the conventional-commits, please apply those rules.
Learn more here.
Check the list of contributors here.
