Spring Boot能否生成application.properties模板？如何从配置源生成配置文档？

Great question! Let's break this down into two clear parts: existing solutions for generating configuration documentation directly from your code, and how to create application.properties templates with comments and default values.

1. Generating Configuration Documentation from Code #

Your initial idea of adding .desc suffixes to config keys works, but it's redundant and not aligned with Spring Boot's best practices. Instead, use these official and community-approved approaches:

Spring Boot Configuration Processor (Official) #

This is the go-to tool for documenting configs in code. It uses annotations and JavaDoc to generate metadata that can be used for IDE hints, validation, and documentation.

Step 1: Add the Dependency

For Maven, add this to your pom.xml:

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

For Gradle:

annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'

Step 2: Document Your Configs with Annotations

Create a configuration properties class and use JavaDoc (or @Description annotations) to add documentation:

@ConfigurationProperties(prefix = "a.b.c")
public class MyAppProperties {
    /**
     * This is the documentation for myProperty
     * Controls the core threshold value for XYZ feature
     */
    private int myProperty = 42;
    
    /**
     * foo is the most important parameter ever!
     * Determines the default fallback string for API responses
     */
    private String foo = "baa";
    
    // Getters and setters required for binding
}

Step 3: Generate Documentation

The processor automatically creates a META-INF/spring-configuration-metadata.json file during build. You can:

• Use IDEs like IntelliJ or Eclipse to view this metadata as hints when editing config files.
• Use plugins like spring-boot-configdocs-maven-plugin to convert the JSON into human-readable docs (HTML, Markdown, or Asciidoc). For example, the Maven plugin can generate a Markdown file with all config keys, descriptions, default values, and data types.

Community Tools #

If you need more customization, check out tools like:

• Spring Boot Config Doc Generator: A lightweight library that parses the configuration metadata and generates clean Markdown/HTML docs.
• Asciidoctor Integration: Combine the metadata with Asciidoctor templates to create fully styled, production-ready documentation.

2. Creating application.properties Templates #

Spring Boot doesn't have a built-in command to generate config templates directly, but you can leverage the configuration metadata we mentioned above to create a template with comments and default values.

Option 1: Use a Plugin #

Plugins like spring-boot-configdocs-maven-plugin can generate a commented application.properties template alongside your documentation. The output will look exactly like what you're aiming for:

# This is the documentation for myProperty
# Controls the core threshold value for XYZ feature
a.b.c.myProperty=42

# foo is the most important parameter ever!
# Determines the default fallback string for API responses
a.b.c.foo=baa

Option 2: Custom Script #

If you need full control, write a simple script (Python, Groovy, etc.) that parses the spring-configuration-metadata.json file and outputs a formatted application.properties file with comments. The JSON includes all necessary info: key names, descriptions, default values, and data types.

Key Takeaway #

Skip the custom .desc config approach—Spring Boot's official tooling already solves this problem cleanly. By using @ConfigurationProperties and the configuration processor, you keep your docs in sync with your code, avoid duplication, and can easily generate both human-readable documentation and user-friendly config templates.

内容的提问来源于stack exchange，提问作者mibutec