Spring Configuration Property Documenter
Tags: springboot, asciidoc, html, markdown
Published: 2023-03-10 10:50:00

---
title: Spring Configuration Property Documenter
published: true
description: A tool to document your properties with ease.
tags: springboot, asciidoc, html, markdown
published_at: 2023-03-10 10:50 +0000
cover_image: https://res.cloudinary.com/practicaldev/image/fetch/s--cj6qL99j--/c_imagga_scale,f_auto,fl_progressive,h_420,q_auto,w_1000/https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bupbqc9fctvw4j7r14it.png
---

## 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:

```xml
<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:

```java
@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:

```json
{
  "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](https://github.com/rodnansol/spring-configuration-property-documenter).

### 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](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/template-customization.adoc#custom-template-compiler).

#### 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](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/samples/multi-module/multi-module-docs/pom.xml).

### How to use the tool?

The core functionalities are built with Java 11 and these functionalities are available through:

- [Maven plugin](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/maven-plugin.adoc)
- [JBang script](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/usage-jbang.adoc)
- [Gradle plugin (Coming soon)](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/gradle-plugin.adoc)

### Maven usage

Just add the following plugin to your `pom.xml` and you are ready to go.

```xml

<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>
```

<p align="center">
<img alt="Final version" src="https://img.shields.io/maven-central/v/org.rodnansol/spring-configuration-property-documenter?label=The%20final%20version%20is%20&style=for-the-badge">
</p>

Check the available Maven goals [here](https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/maven-plugin.adoc#available-goals-and-config).

### Template customization

The templates can be customized if the default one is not fitting your requirements, please read the docs about that [here](https://github.com/rodnansol/spring-configuration-property-documenter/tree/master/samples).

![AsciiDoc Example](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o1cobryz1gzvkmfnu27b.png)

---

![AsciiDoc Example 2](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/t11190vbiz0bnehyeeav.png)


### Checkout the samples & docs

Feel free to check out the samples and documentation because it will give a wider knowledge about the how-tos.

- [Samples](https://github.com/rodnansol/spring-configuration-property-documenter/tree/master/samples)
- [Docs](https://github.com/rodnansol/spring-configuration-property-documenter/tree/master/docs)

### Are you using Spring Boot with Quarkus?

If yes, do not worry, we got you covered, check out this [sample](https://github.com/rodnansol/spring-configuration-property-documenter/tree/master/samples/quarkus-spring-boot-single-module).

## Follow Rodnan Sol for more

<p align="center">
<a href="https://twitter.com/rodnansol"><img alt="Twitter followers" src="https://img.shields.io/twitter/follow/rodnansol?logo=twitter&style=for-the-badge"></a>
<a href="https://github.com/rodnansol"><img alt="GitHub followers" src="https://img.shields.io/github/followers/rodnansol?label=Follow%20rodnansol&logo=github&style=for-the-badge"></a>
<a href="https://dcbadge.vercel.app/api/server/USyh6XUjvP"><img src="https://dcbadge.vercel.app/api/server/USyh6XUjvP"></a>
</p>

## Follow the author too

<p align="center"> 
<a href="https://twitter.com/therealhnk"><img alt="Twitter followers" src="https://img.shields.io/twitter/follow/therealhnk?logo=twitter&style=for-the-badge"></a>
<a href="https://github.com/nandorholozsnyak"><img alt="GitHub followers" src="https://img.shields.io/github/followers/nandorholozsnyak?label=Follow%20nandorholozsnyak&logo=github&style=for-the-badge"></a>
</p>