如何生成 Spring 属性文档

您是否正在努力使 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 配置处理器作为依赖项。

  org.springframework.boot
  spring-boot-configuration-processor
  true

生成文档

该插件能够生成四种不同格式的文档：

• ASCII 医生

• 降价

• 超文本标记语言

• XML

为了生成文档，您只需将插件添加到构建部分（在添加 Spring 配置处理器依赖项旁边）。对于每种格式类型，都会添加一个执行。如果您只需要 markdown 格式的文档，只需删除其他执行即可。

  
    
      org.rodnansol
      spring-configuration-property-documenter-maven-plugin
      0.6.1
      
        
          generate-adoc
          process-classes
          
            generate-property-document
          
          
            ADOC
          
        
        
          generate-markdown
          process-classes
          
            generate-property-document
          
          
            MARKDOWN
          
        
        
          generate-html
          process-classes
          
            generate-property-document
          
          
            HTML
          
        
        
          generate-xml
          process-classes
          
            generate-property-document
          
          
            XML
          
        
      
    
  

使用 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。

  generate-markdown
  process-classes
  
    generate-property-document
  
  
    MARKDOWN
      
        false
      
  

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

描述和默认值

在上面的输出中，您注意到属性的描述和默认值 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 项目受益。

到此这篇关于如何生成 Spring 属性文档的文章就介绍到这了, 更多相关内容可以在右上角搜索或继续浏览下面的相关文章，希望大家以后多多支持 TOY 模板网！

原文地址:https://www.toymoban.com/diary/java/405.html

如若转载，请注明出处：如若内容造成侵权 / 违法违规 / 事实不符，请联系站长进行投诉反馈，一经查实，立即删除！