记录spring（boot）配置属性 [英] documenting spring (boot) configuration properties

问题描述

我正在寻找一个解决方案来为我的应用程序中使用的弹簧配置属性创建文档。

I am searching for a solution to create a documentation for spring configuration properties used in my application.

例如，我有以下类Person的定义使用application.properties文件中的属性person.age来设置该人的年龄。

For example I have the following definition of class 'Person' which uses the property 'person.age' from the application.properties file to set the age of the person.

public class Person {
  @Value("${person.age:21}")
  private int age;

  public Person(){}

  private int getAge(){ return age; }
}

我想要的是一个文档，说明哪个属性在做什么以及该属性的默认值（如果有）。也许通过使用@Value注释的属性上方的注释，如：

What I want to have, is a documentation stating which property is doing what and what is the default for that property if any. Maybe through a comment above the attribute with the @Value annotation like:

/**
* Used to set the age.
*/
@Value("${person.age:21}")
private int age;

导致以下情况：

person.age, default 21: Used to set the age.

我没有绑定到输出的格式或其他任何东西。我唯一需要的是为我的属性提供某种文档。最好的办法是将它直接写入java代码，如果可能的话。

I am not bound to the format of the output or anything else. The only thing I want is to have some kind of documentation for my properties. Best thing would be to write it directly into the java code, if possible.

我搜索了，但到现在为止找不到任何有用的东西。我发现唯一的事情是使用注释处理器生成自己的元数据（ http://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html ）。
但我不知道这是否会奏效。如果是这样，我想知道是否有没有开箱即用的解决方案。我不能想像我是唯一想要为Spring属性提供某种文档的人。

I searched around but couldn't find anything useful up to now. The only thing I found is to generate my own metadata using the annotation processor (http://docs.spring.io/spring-boot/docs/current/reference/html/configuration-metadata.html). But I am not sure if this will work. If so I would wonder if there is no "out of the box" solution for that kind of problem. I can not imagine that I am the only one who wants to have some kind of documentation for spring properties.

非常感谢您的任何提示。 >

Thank you very much for any kind of hint.

推荐答案

在Andreas的提示之后，我来到了以下解决方案。

After the hint from Andreas, I came to the following solution.

我使用 @ConfigurationProperties 注释创建了一个新的配置类，它具有 age 的属性：

I made a new configuration class with the @ConfigurationProperties annotation which holds the attribute age:

@ConfigurationProperties(prefix = "person")
public class PersonProperties {

  /**
  * Configures the age of person.
  */
  private int age = 18;

  private int getAge(){ return age; }
  private int setAge(int age){ this.age = age; }
}

我自动连接到这个我们的类中的PersonProperties 以前通过 @Value（$ {person.age}）直接访问该属性。在上面的例子中，它将是：

I autowired this PersonProperties inside the classes I formerly accessed the property directly via @Value("${person.age}"). In the example above it would be:

public class Person {
  @Autowire
  private PersonProperties properties;

  public Person(){}

  private int getAge(){ return properties.getAge; }
}

要获取该属性的文档，我只需激活注释

To get the documentation for the property, I just had to activate the annotation processing.

对于IntelliJ IDEA ：
转到设置 - > 构建，执行编辑器 - > 注释处理器并标记启用注释处理。对于其余的设置，我选择了默认值。

For IntelliJ IDEA: go to Settings -> Build, Execution, Deployment -> Compiler -> Annotation Processors and mark Enable annotation processing. For the rest of the settings I chose the defaults.

运行构建后，结果（JSON）将位于项目文件夹中的 .\target\\ \\ classes \META-INF \spring-configuration-metadata.json 。

After running the build, the result (JSON) will be in project folder in .\target\classes\META-INF\spring-configuration-metadata.json.

这是我所得到的文档：

{
  "groups": [
    {
      "name": "person",
      "type": "com.test.PersonProperties",
      "sourceType": "com.test.PersonProperties"
    }
  ],
  "properties": [
    {
      "name": "person.age",
      "type": "java.lang.Integer",
      "description": "Configures the age of person.",
      "sourceType": "com.test.PersonProperties",
      "defaultValue": 18
    }
  ],
  "hints": []
}

使用此解决方案，我仍然可以设置属性

With this solution I still can set the property

something.person.age=25

在 application.pro我的应用程序的perties 文件，同时有我的属性记录。

in the application.properties file of my application and at the same time have my property documented.

现在我正在寻找解决方案，使这种文档不知何故好看（可能只是通过简单的JSON脚本和CSS），并获得这个文档使用验证注释。
但是这些是不同的问题。

Now I am searching for solution to make that kind of documentation somehow nice looking (maybe just via simple JSON script and css) and to get this documentation working with validation annotations. But these are different questions.

感谢 Andreas < a>为这个伟大的提示。

Thanks to Andreas for that great hint.

这篇关于记录spring（boot）配置属性的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！