当前位置：Java -> 如何生成Spring属性文档

如何生成Spring属性文档

您是否在努力保持您的Spring配置属性文档与代码一致呢？在这篇博客中，您将了解Spring配置属性文档生成器Maven插件，它可以为您解决这个问题。祝您愉快！

介绍

几乎每个Spring（Boot）应用程序都使用配置属性。这些配置属性确保您的应用程序中的某些项目可以通过application.properties（或YAML）文件进行配置。然而，还需要对这些属性进行文档化，以便他人了解这些属性的含义、如何使用等。通常在README文件中记录这些信息。这个README文件需要手动维护，而这些属性又存在于一个包含文档和注解的Java类中。

当文档位于一个地方（靠近代码的Java类）并且可以从代码中生成文档时，这岂不是太棒了？好消息！这正是Spring配置属性文档生成器Maven插件将为您实现的！在本文的其余部分，您将探讨这个Maven插件的一些特性，以及如何轻松地将其整合到您的项目中。官方文档更详尽，可在此处找到。

本博客中使用的源代码可在GitHub上找到。

示例应用程序

首先，您需要创建一个基本的示例应用程序。转到Spring Initializr，并选择依赖项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);
    }

}

在config包中创建一个配置类MyFirstProperties。该配置类使用构造函数绑定。另请参阅前一篇文章“解释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;
    }
}

此外，在controller包中添加ConfigurationController，该控制器返回属性。此控制器仅作为如何使用属性的示例添加，对本博客并不相关。

构建应用程序。

$ mvn clean verify

运行应用程序。

$ mvn spring-boot:run

调用在ConfigurationController中配置的端点。

$ curl http://localhost:8080/configuration

查看目录target/classes/META-INF。这里会有一个文件spring-configuration-metadata.json，其中包含有关配置类的元数据。这些信息将被Spring配置属性文档生成器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依赖项旁边）。对于每种格式类型，都会添加一个执行。如果只希望获得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多模块项目，则可以将不同模块的所有属性合并到一个文件中。如何实现这一点在文档中有详细说明。

自定义输出

在本文的其余部分，您将继续使用Markdown格式。在上述屏幕截图中，您会注意到一个未知组已添加。该组也是空的。默认情况下，输出中始终会添加此组，但可以通过markdownCustomization参数将其移除。还有许多其他可用的自定义选项，在文档中列出。为了在输出中禁用未知组，您可以将参数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>

执行Markdown生成，您会注意到输出中不再存在未知组。

描述和默认值

在上述输出中，您会注意到属性的描述和stringProperty的默认值为空。

创建一个新的配置类MySecondProperties。在表示属性的字段上方添加Javadoc，并在构造函数中stringProperty之前添加@DefaultValue注解。

@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，它还包含一个stringProperty和一个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文档，您会注意到文档还包含嵌套属性。

Records

由于配置属性是不可变的，最好使用Java records而不是使用Lombok。创建一个名为MyFourthProperties的配置类，并使用Java records。问题是在哪里添加属性的描述，因为没有字段可以添加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文档，您会注意到描述为空。