您是否正在努力使 Spring 配置屬性的文檔與代碼保持一致？了解如何解決本文中的問(wèn)題。
介紹
幾乎每個(gè) Spring（啟動(dòng)）應(yīng)用程序都會(huì)使用配置屬性。這些配置屬性確保應(yīng)用程序中的某些項(xiàng)目可以通過(guò) application.properties（或 YAML）文件進(jìn)行配置。然而，還需要記錄這些屬性，以便人們了解這些屬性的含義、如何使用它們等。這通常記錄在自述文件中。當(dāng)屬性存在于還包含文檔和注釋的 Java 類(lèi)中時(shí)，需要手動(dòng)維護(hù)此 README 文件。
如果文檔位于一個(gè)位置（Java 類(lèi)，靠近代碼）并且可以從代碼中生成文檔，這不是很好嗎？好消息！這正是Spring Configuration Property Documenter Maven 插件(https://github.com/rodnansol/spring-configuration-property-documenter)將為您做的事情！在本文的其余部分中，您將探索此 Maven 插件的一些功能以及如何輕松地將其合并到您的項(xiàng)目中。官方文檔更詳細(xì)，可以在這里找到(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/index.adoc)。
這篇博文中使用的資源可以在GitHub上找到。(https://github.com/mydeveloperplanet/myspringconfigdocplanet)
申請(qǐng)樣本
首先，您需要?jiǎng)?chuàng)建一個(gè)基本的示例應(yīng)用程序。導(dǎo)航到Spring Initializr(https://start.spring.io/)并選擇依賴項(xiàng)Spring Web、Lombok和Spring Configuration Processor。
使用 .注釋主 Spring Boot 應(yīng)用程序類(lèi)@ConfigurationPropertiesScan。
@SpringBootApplication
@ConfigurationPropertiesScan("com.mydeveloperplanet.myspringconfigdocplanet.config")
public class MySpringConfigDocPlanetApplication {
public static void main(String[] args) {
SpringApplication.run(MySpringConfigDocPlanetApplication.class, args);
}
}MyFirstProperties在包中創(chuàng)建一個(gè)配置類(lèi)config。配置類(lèi)使用構(gòu)造函數(shù)綁定。另請(qǐng)參閱之前的文章“ Spring Boot 配置屬性解釋”，了解有關(guān)創(chuàng)建配置屬性的不同方法的更多信息。
@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;
}
}此外，還將 a添加到返回屬性的ConfigurationController包中。controller該控制器僅作為如何使用屬性的示例添加。它與本博客沒(méi)有任何關(guān)系。
構(gòu)建應(yīng)用程序。
$ mvn clean verify
運(yùn)行應(yīng)用程序。
$ mvn spring-boot:run
文章來(lái)源地址http://www.zghlxwxcb.cn/article/405.html
調(diào)用 中配置的端點(diǎn)ConfigurationController。
$ curl http://localhost:8080/configuration
看一下目錄target/classes/META-INF。spring-configuration-metadata.json這里有一個(gè)文件，其中包含有關(guān)配置類(lèi)的元數(shù)據(jù)。Spring Configuration Property Documenter Maven 插件使用此信息來(lái)生成文檔。
生成此元數(shù)據(jù)文件是因?yàn)槟砑恿薙pring 配置處理器作為依賴項(xiàng)。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency>
生成文檔
該插件能夠生成四種不同格式的文檔：
ASCII 醫(yī)生
降價(jià)
超文本標(biāo)記語(yǔ)言
XML
為了生成文檔，您只需將插件添加到構(gòu)建部分（在添加 Spring 配置處理器依賴項(xiàng)旁邊）。對(duì)于每種格式類(lèi)型，都會(huì)添加一個(gè)執(zhí)行。如果您只需要 markdown 格式的文檔，只需刪除其他執(zhí)行即可。
<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 執(zhí)行構(gòu)建時(shí)會(huì)生成文檔，但快速的方法是執(zhí)行目標(biāo)process-classes。
$ mvn process-classes
或者您可以調(diào)用特定的執(zhí)行。
$ mvn spring-configuration-property-documenter:generate-property-document@generate-markdown
看一下目錄target/property-docs。對(duì)于每種類(lèi)型，都會(huì)添加配置屬性的文檔。
ASCII Doctor 格式
Markdown 格式
HTML 格式
XML 格式顯示起來(lái)有點(diǎn)復(fù)雜，但它包含上述內(nèi)容的 XML 表示形式。
如果您有一個(gè) Maven 多模塊項(xiàng)目，您可以將不同模塊的所有屬性合并到一個(gè)文件中。文檔中描述了如何執(zhí)行此操作。(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/maven-plugin.adoc)
自定義輸出
在本文的其余部分中，您將繼續(xù)使用 Markdown 格式。在上面的屏幕截圖中，您注意到添加了一個(gè)未知組。這個(gè)群也是空的。默認(rèn)情況下，該組始終添加到輸出中，但可以通過(guò)參數(shù)將其刪除markdownCustomization。文檔(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/template-customization.adoc#template-customizations)中列出了更多可用的自定義項(xiàng)。為了禁用輸出中的未知組，請(qǐng)將參數(shù)設(shè)置includedUnknownGroup為false。
<execution> <id>generate-markdown</id> <phase>process-classes</phase> <goals> <goal>generate-property-document</goal> </goals> <configuration> <type>MARKDOWN</type> <markdownCustomization> <includeUnknownGroup>false</includeUnknownGroup> </markdownCustomization> </configuration> </execution>
執(zhí)行降價(jià)生成，您會(huì)注意到輸出中不再存在未知組。
描述和默認(rèn)值
在上面的輸出中，您注意到屬性的描述和默認(rèn)值stringProperty是空的。
創(chuàng)建一個(gè)新的配置類(lèi)MySecondProperties。在表示屬性的字段上方添加 Javadoc，并在構(gòu)造函數(shù)@DefaultValue之前添加注釋。stringProperty
@Getter
@ConfigurationProperties("my.second.properties")
public class MySecondProperties {
/**
* This is the description for stringProperty
*/
private final String stringProperty;
/**
* This is the description for booleanProperty
*/
private final boolean booleanProperty;
public MySecondProperties(@DefaultValue("default value for stringProperty") String stringProperty,
boolean booleanProperty) {
this.stringProperty = stringProperty;
this.booleanProperty = booleanProperty;
}
}生成文檔，您會(huì)注意到存在描述并且填充了默認(rèn)值stringProperty。
這太棒了，不是嗎？文檔與代碼一起就在那里，并且 Markdown 中的文檔是從它生成的。
嵌套屬性
它也適用于嵌套屬性嗎？讓我們來(lái)看看吧。創(chuàng)建一個(gè)MyThirdProperties具有嵌套屬性的配置類(lèi)nestedProperty，其中還包含 astringProperty和 a booleanProperty。默認(rèn)booleanProperty為 true。
@Getter
@ConfigurationProperties("my.third.properties")
public class MyThirdProperties {
/**
* This is the description for stringProperty
*/
private final String stringProperty;
/**
* This is the description for booleanProperty
*/
private final boolean booleanProperty;
private final NestedProperty nestedProperty;
public MyThirdProperties(@DefaultValue("default value for stringProperty") String stringProperty,
boolean booleanProperty,
@DefaultValue NestedProperty nestedProperty) {
this.stringProperty = stringProperty;
this.booleanProperty = booleanProperty;
this.nestedProperty = nestedProperty;
}
@Getter
public static class NestedProperty {
/**
* This is the description for nested stringProperty
*/
private final String stringProperty;
/**
* This is the description for nested booleanProperty
*/
private final boolean booleanProperty;
public NestedProperty(@DefaultValue("default value for nested stringProperty") String stringProperty,
@DefaultValue("true") boolean booleanProperty) {
this.stringProperty = stringProperty;
this.booleanProperty = booleanProperty;
}
}生成 Markdown 文檔，您會(huì)注意到該文檔還包含嵌套屬性。
記錄
由于配置屬性是不可變的，因此使用 Java 記錄比使用 Lombok 更好。創(chuàng)建配置類(lèi)MyFourthProperties并使用Java記錄。問(wèn)題是在哪里添加屬性描述，因?yàn)闆](méi)有可以添加 Javadoc 的字段。
/**
* @param stringProperty This is the description for stringProperty
* @param booleanProperty This is the description for booleanProperty
*/
@ConfigurationProperties("my.fourth.properties")
public record MyFourthProperties (@DefaultValue("default value for stringProperty") String stringProperty,
@DefaultValue("true") boolean booleanProperty) {
}生成 Markdown 文檔并注意描述為空。
然而，這不是插件的問(wèn)題。文件中的描述為空spring-configuration-metadata.json，插件僅使用此信息。
Stack Overflow 上有人問(wèn)了這個(gè)問(wèn)題。希望接下來(lái)會(huì)有答案。(https://stackoverflow.com/questions/76935707/how-to-use-the-configuration-processor-with-records)
總結(jié)
Spring Configuration Property Documenter Maven 插件是一項(xiàng)偉大的舉措，旨在使文檔更接近代碼并根據(jù)代碼生成文檔。它填補(bǔ)了我認(rèn)為的一個(gè)空白，這使幾乎所有 Spring 項(xiàng)目受益。文章來(lái)源：http://www.zghlxwxcb.cn/article/405.html
到此這篇關(guān)于如何生成 Spring 屬性文檔的文章就介紹到這了,更多相關(guān)內(nèi)容可以在右上角搜索或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
