Quarkus中如何从application.properties自动生成Asciidocs文档？

API 探路者

2026-6-28

在Quarkus中自动生成Asciidoc格式的配置文档

是的，Quarkus提供了官方工具来自动生成与官方风格一致的Asciidoc配置文档，以下是具体实现方式：

1. 核心工具：Quarkus构建插件的配置文档生成目标

Quarkus的Maven/Gradle插件内置了generate-config-docs目标，能够扫描项目中的配置项（包括application.properties里的内置和自定义配置），生成符合官方样式的Asciidoc文档。

2. Maven项目执行步骤

在项目根目录执行以下命令：

./mvnw quarkus:generate-config-docs -Dquarkus.config.output-format=asciidoc -Dquarkus.config.output-directory=target/docs

参数说明：

quarkus.config.output-format：指定输出格式为asciidoc
quarkus.config.output-directory：指定文档输出目录

3. Gradle项目执行步骤

在项目根目录执行以下命令：

./gradlew generateConfigDocs --quarkus.config.output-format=asciidoc --quarkus.config.output-directory=build/docs

4. 为配置项补充描述（可选）

如果是自定义配置项，或者需要为内置配置补充更详细的说明，可通过配置类添加Javadoc注释，示例如下：

import io.smallrye.config.ConfigMapping;
import java.util.List;

@ConfigMapping(prefix = "quarkus.lambda")
public interface LambdaConfig {
    /**
     * 指定Lambda函数允许抛出的预期异常列表，这些异常不会被标记为错误
     */
    List<String> expectedExceptions();

    /**
     * Lambda函数的处理程序全类名，格式为`包名.类名::方法名`
     */
    String handler();
}

添加注释后，生成的Asciidoc文档会自动包含这些描述，与官方文档样式保持一致。