您是否正在努力使 Spring 配置属性的文档与代码保持一致？了解如何解决本文中的问题。
介绍
几乎每个 Spring（启动）应用程序都会使用配置属性。这些配置属性确保应用程序中的某些项目可以通过 application.properties（或 YAML）文件进行配置。然而，还需要记录这些属性，以便人们了解这些属性的含义、如何使用它们等。这通常记录在自述文件中。当属性存在于还包含文档和注释的 Java 类中时，需要手动维护此 README 文件。
如果文档位于一个位置（Java 类，靠近代码）并且可以从代码中生成文档，这不是很好吗？好消息！这正是Spring Configuration Property Documenter Maven 插件(https://github.com/rodnansol/spring-configuration-property-documenter)将为您做的事情！在本文的其余部分中，您将探索此 Maven 插件的一些功能以及如何轻松地将其合并到您的项目中。官方文档更详细，可以在这里找到(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/index.adoc)。
这篇博文中使用的资源可以在GitHub上找到。(https://github.com/mydeveloperplanet/myspringconfigdocplanet)
申请样本
首先，您需要创建一个基本的示例应用程序。导航到Spring Initializr(https://start.spring.io/)并选择依赖项Spring Web、Lombok和Spring Configuration Processor。
使用 .注释主 Spring Boot 应用程序类@ConfigurationPropertiesScan。
@SpringBootApplication
@ConfigurationPropertiesScan("com.mydeveloperplanet.myspringconfigdocplanet.config")
public class MySpringConfigDocPlanetApplication {
public static void main(String[] args) {
SpringApplication.run(MySpringConfigDocPlanetApplication.class, args);
}
}MyFirstProperties在包中创建一个配置类config。配置类使用构造函数绑定。另请参阅之前的文章“ Spring Boot 配置属性解释”，了解有关创建配置属性的不同方法的更多信息。
@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该控制器仅作为如何使用属性的示例添加。它与本博客没有任何关系。
构建应用程序。
$ mvn clean verify
运行应用程序。
$ mvn spring-boot:run
文章来源地址https://www.toymoban.com/diary/java/405.html
调用 中配置的端点ConfigurationController。
$ curl http://localhost:8080/configuration
看一下目录target/classes/META-INF。spring-configuration-metadata.json这里有一个文件，其中包含有关配置类的元数据。Spring Configuration Property Documenter Maven 插件使用此信息来生成文档。
生成此元数据文件是因为您添加了Spring 配置处理器作为依赖项。
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-configuration-processor</artifactId> <optional>true</optional> </dependency>
生成文档
该插件能够生成四种不同格式的文档：
ASCII 医生
降价
超文本标记语言
XML
为了生成文档，您只需将插件添加到构建部分（在添加 Spring 配置处理器依赖项旁边）。对于每种格式类型，都会添加一个执行。如果您只需要 markdown 格式的文档，只需删除其他执行即可。
<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。对于每种类型，都会添加配置属性的文档。
ASCII Doctor 格式
Markdown 格式
HTML 格式
XML 格式显示起来有点复杂，但它包含上述内容的 XML 表示形式。
如果您有一个 Maven 多模块项目，您可以将不同模块的所有属性合并到一个文件中。文档中描述了如何执行此操作。(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/maven-plugin.adoc)
自定义输出
在本文的其余部分中，您将继续使用 Markdown 格式。在上面的屏幕截图中，您注意到添加了一个未知组。这个群也是空的。默认情况下，该组始终添加到输出中，但可以通过参数将其删除markdownCustomization。文档(https://github.com/rodnansol/spring-configuration-property-documenter/blob/master/docs/modules/ROOT/pages/template-customization.adoc#template-customizations)中列出了更多可用的自定义项。为了禁用输出中的未知组，请将参数设置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>
执行降价生成，您会注意到输出中不再存在未知组。
描述和默认值
在上面的输出中，您注意到属性的描述和默认值stringProperty是空的。
创建一个新的配置类MySecondProperties。在表示属性的字段上方添加 Javadoc，并在构造函数@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;
}
}生成文档，您会注意到存在描述并且填充了默认值stringProperty。
这太棒了，不是吗？文档与代码一起就在那里，并且 Markdown 中的文档是从它生成的。
嵌套属性
它也适用于嵌套属性吗？让我们来看看吧。创建一个MyThirdProperties具有嵌套属性的配置类nestedProperty，其中还包含 astringProperty和 a booleanProperty。默认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 文档，您会注意到该文档还包含嵌套属性。
记录
由于配置属性是不可变的，因此使用 Java 记录比使用 Lombok 更好。创建配置类MyFourthProperties并使用Java记录。问题是在哪里添加属性描述，因为没有可以添加 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 文档并注意描述为空。
然而，这不是插件的问题。文件中的描述为空spring-configuration-metadata.json，插件仅使用此信息。
Stack Overflow 上有人问了这个问题。希望接下来会有答案。(https://stackoverflow.com/questions/76935707/how-to-use-the-configuration-processor-with-records)
总结
Spring Configuration Property Documenter Maven 插件是一项伟大的举措，旨在使文档更接近代码并根据代码生成文档。它填补了我认为的一个空白，这使几乎所有 Spring 项目受益。文章来源：https://www.toymoban.com/diary/java/405.html
到此这篇关于如何生成 Spring 属性文档的文章就介绍到这了,更多相关内容可以在右上角搜索或继续浏览下面的相关文章，希望大家以后多多支持TOY模板网！
