Spring Configuration Property Documenter

Maven Central Apache 2.0 rodnansol Discord

  • 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.

Goals

Introduction

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?

Project

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
An example configuration property class
@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": []
}

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.

You can use our Maven plugin or our Gradle plugin to utilize the document generation tool.

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.

Results

AsciiDoc
image$asciidoc result
image$asciidoc result 2
Markdown
image$markdown result
HTML
image$html result
XML
image$xml result

Try out quickly with Maven

Via direct plugin execution

mvn clean package  \
  org.rodnansol:spring-configuration-property-documenter-maven-plugin:0.7.0:generate-property-document \
  -Dtype=ADOC

An Asciidoc based property documentation should be available in your target/property-docs folder.

Via minimal pom.xml configuration

pom.xml
<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.

Setup

Requirements

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.

Modules

The project is currently having the following modules:

spring-configuration-property-documenter-core

This Maven module contains the "core" codebase for the whole project, other modules are just entry points to this core module.

spring-configuration-property-documenter-maven-plugin

This Maven module is a Maven plugin implementation, please check the Maven plugin part for the available goals and configuration.

jbang

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.

spring-configuration-property-documenter-gradle-plugin

This Maven module is a Gradle plugin implementation, please check the Gradle part for the available goals and configuration.

Usage

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.

Entry points

Customization

Contribution

Fork

Please fork the project if you would like to contribute.

How to build the project?

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 install and then mvn package -f samples/pom.xml

Code formatter

The project contains a .editorconfig file, and it should be utilized as well.

During build time Checkstyle checks the conventions.

Commit messages

The commit messages are based on the conventional-commits, please apply those rules.

Learn more here.

Contributors

Check the list of contributors here.