在本博客中，您将了解 Spring Configuration Property Documenter Maven 插件，它可以为您解决这个问题。
几乎每个 Spring（启动）应用程序都会使用配置属性。这些配置属性确保应用程序中的某些项目可以通过 application.properties（或 yaml）文件进行配置。
然而，还需要记录这些属性，以便有人知道这些属性的含义、如何使用它们等。这通常记录在自述文件中。当属性存在于还包含文档和注释的 Java 类中时，需要手动维护此 README 文件。
如果文档位于一个位置（Java 类，靠近代码）并且可以从代码中生成文档，这不是很好吗？
好消息！这正是Spring Configuration Property Documenter Maven 插件将为您做的事情！
本博客中使用的资源可以在GitHub上找到。
首先，您需要创建一个基本的示例应用程序。
用@ConfigurationPropertiesScan注释主 Spring Boot 应用程序类：
@SpringBootApplication
@ConfigurationPropertiesScan("com.mydeveloperplanet.myspringconfigdocplanet.config")
public class MySpringConfigDocPlanetApplication {
public static void main(String[] args) {
SpringApplication.run(MySpringConfigDocPlanetApplication.class, args);
}
}
|
在包 config 中创建一个配置类 MyFirstProperties。该配置类使用了构造函数绑定。
@Getter
@ConfigurationProperties("my.first.properties")
public class MyFirstProperties {
private final String stringProperty;
private final boolean booleanProperty;
public MyFirstProperties(String stringProperty, boolean booleanProperty) {
this.stringProperty = stringProperty;
this.booleanProperty = booleanProperty;
}
}
|
此外，包控制器中还添加了一个 ConfigurationController，用于返回属性。添加该控制器只是为了举例说明如何使用属性，与本博客无关。
构建运行：
mvn clean verify
mvn spring-boot:run
调用：
curl http://localhost:8080/configuration
请查看目录 target/classes/META-INF。这里有一个文件 spring-configuration-metadata.json，其中包含有关配置类的元数据。Spring Configuration Property Documenter Maven 插件会使用这些信息来生成文档。
生成该元数据文件是因为添加了 Spring Configuration Processor 作为依赖项。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-configuration-processor</artifactId>
<optional>true</optional>
</dependency>
|
生成文档
该插件可生成四种不同格式的文档：
- ASCII Doctor
- Markdown
- HTML
- XML
要生成文档，只需将插件添加到构建部分（添加 Spring Configuration Processor 依赖项旁边）即可。每种格式类型都会添加一个执行程序。如果只想要标记符格式的文档，只需移除其他执行项即可。<build>
<plugins>
<plugin>
<groupId>org.rodnansol</groupId>
<artifactId>spring-configuration-property-documenter-maven-plugin</artifactId>
<version>0.6.1</version>
<executions>
<execution>
<id>generate-adoc</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>ADOC</type>
</configuration>
</execution>
<execution>
<id>generate-markdown</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>MARKDOWN</type>
</configuration>
</execution>
<execution>
<id>generate-html</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>HTML</type>
</configuration>
</execution>
<execution>
<id>generate-xml</id>
<phase>process-classes</phase>
<goals>
<goal>generate-property-document</goal>
</goals>
<configuration>
<type>XML</type>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
|
文件将在使用 Maven 执行构建时生成，但快速方法是执行 process-classes 目标。
mvn process-classes
您也可以调用特定的执行。
mvn spring-configuration-property-documenter:generate-property-document@generate-markdown
请查看目录 target/property-docs。每种类型都添加了配置属性的文档。
如果您有一个 Maven 多模块项目，可以将不同模块的所有属性合并到一个文件中。文档documentation中介绍了如何做到这一点。
结论
Spring Configuration Property Documenter Maven 插件是一项伟大的创举，它让文档更贴近代码，并根据代码生成文档。在我看来，它填补了一个空白，几乎惠及所有 Spring 项目。