Spring Configuration Property Documenter

#springboot #asciidoc #html #markdown

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>