在本部落格中，您將瞭解 Spring Configuration Property Documenter Maven 外掛，它可以為您解決這個問題。
幾乎每個 Spring（啟動）應用程式都會使用配置屬性。這些配置屬性確保應用程式中的某些專案可以透過 application.properties（或 yaml）檔案進行配置。
然而，還需要記錄這些屬性，以便有人知道這些屬性的含義、如何使用它們等。這通常記錄在自述檔案中。當屬性存在於還包含文件和註釋的 Java 類中時，需要手動維護此 README 檔案。
如果文件位於一個位置（Java 類，靠近程式碼）並且可以從程式碼中生成文件，這不是很好嗎？
好訊息！這正是Spring Configuration Property Documenter Maven 外掛將為您做的事情！
本部落格中使用的資源可以在GitHub上找到。
首先，您需要建立一個基本的示例應用程式。
用@ConfigurationPropertiesScan註釋主 Spring Boot 應用程式類：
@SpringBootApplication
@ConfigurationPropertiesScan(<font>"com.mydeveloperplanet.myspringconfigdocplanet.config")
public class MySpringConfigDocPlanetApplication {
public static void main(String[] args) {
SpringApplication.run(MySpringConfigDocPlanetApplication.class, args);
}
}
|
在包 config 中建立一個配置類 MyFirstProperties。該配置類使用了建構函式繫結。
@Getter
@ConfigurationProperties(<font>"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 專案。