ConfigurationProperties配置报黄、无描述的问题

ConfigurationProperties配置报黄、无描述的问题

• ConfigurationProperties配置报黄、无描述的问题
  • ConfigurationProperties与NestedConfigurationProperty
  • ConfigurationProperties使用案例说明
    • 假设你的配置类是这样的
    • 那么生成的配置说明文件
    • [分析配置说明文件 & 使用验证，可知](#分析配置说明文件 & 使用验证，可知)
  • 配置报黄、无配置描述的最终结论

ConfigurationProperties与NestedConfigurationProperty

• @ConfigurationProperties 用于标记顶层配置类，而 @NestedConfigurationProperty 则用于标记该类中的嵌套配置类。

• @ConfigurationProperties 注解使得Spring框架能够自动将配置文件中的属性绑定到Java对象的字段上。

• @NestedConfigurationProperty 注解则使得嵌套的配置属性也能被正确地绑定。

ConfigurationProperties使用案例说明

假设你的配置类是这样的

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.NestedConfigurationProperty;

import java.util.List;
import java.util.Map;

@Data
@ConfigurationProperties(prefix = "springdoc.zoo-knife4j")
public class ZooKnife4jProperties {
    
    /*
     * 【1】：正确list demo
     */
    private List<FileTypeMapping> listDemo;
    
    /*
     * 【2】：正确list demo
     */
    private Map<String, FileTypeMapping> mapDemo;
    
    /*
     * 【3】：错误list demo
     */
    @NestedConfigurationProperty
    private List<FileTypeMapping> listErrorDemo;
    
    /*
     * 【4】：错误list demo
     */
    @NestedConfigurationProperty
    private Map<String, FileTypeMapping> mapErrorDemo;
    
    /*
     * 【5】：正确single object demo1
     */
    private Info info;
    
    /*
     * 【6】：正确single object demo2
     */
    @NestedConfigurationProperty
    private SecurityScheme securityScheme;
    
    @Data
    public static class SecurityScheme {
        
        /**
         * 当前鉴权策略的名称
         */
        private String schemeName = "defaultBearerAuth";
        
        /**
         * 请求头 - key
         */
        private String headerKey;
        
        /**
         * 安全方案的名称
         * <p>
         * @see io.swagger.v3.oas.models.security.SecurityScheme#getScheme()
         */
        private String scheme;
    
        /**
         * 当前权限的风格
          <p>
         * @see io.swagger.v3.oas.models.security.SecurityScheme#getBearerFormat()
         */
        private String bearerFormat;
 
    }
}

那么生成的配置说明文件

打包后生成的生成的配置说明文件spring-configuration-metadata.json

是这样的

{
    "name": "springdoc.zoo-knife4j.list-demo",
    "type": "java.util.List<com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.FileTypeMapping>",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties"
},
{
    "name": "springdoc.zoo-knife4j.map-demo",
    "type": "java.util.Map<java.lang.String,com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.FileTypeMapping>",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties"
},
{
    "name": "springdoc.zoo-knife4j.list-error-demo",
    "type": "java.util.List",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties",
    "sourceMethod": "getListErrorDemo()"
},
{
    "name": "springdoc.zoo-knife4j.map-error-demo",
    "type": "java.util.Map",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties",
    "sourceMethod": "getMapErrorDemo()"
},
{
    "name": "springdoc.zoo-knife4j.info",
    "type": "io.swagger.v3.oas.models.info.Info",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties"
},
{
    "name": "springdoc.zoo-knife4j.security-scheme",
    "type": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties$SecurityScheme",
    "sourceType": "com.ideaaedi.zoo.diy.artifact.apidoc.knife4j.properties.ZooKnife4jProperties",
    "sourceMethod": "getSecurityScheme()"
}

分析配置说明文件 & 使用验证，可知

生成的配置说明文件中，

配置类中【1】、【2】、【5】、【6】是符合预期的，因为type不仅把具体的类型生成出来了，还把泛型也生成出来了

配置类中【3】、【4】是不符合预期的，它丢失了泛型，这就导致：你在写配置文件时，你的配置会报黄，虽然功能使用上没影响

配置报黄、无配置描述的最终结论

在进行了其它实验之后，形成了以下结论

1. 如果字段是一个简单类，可标可不标@NestedConfigurationProperty

   如上面的：SecurityScheme、Info

2. 如果字段是一个简单类，那这个简单类可以是正常类、也可以是内部类，都无所谓

   如上面的：SecurityScheme、Info

3. 如果字段是一个嵌套复杂类，那么不需要标@NestedConfigurationProperty

   如上面的：List<FileTypeMapping>、Map<String, FileTypeMapping>

4. 如果字段是一个嵌套复杂类，那么这个复杂类涉及到的嵌套类，最好不要是内部类（内部类的话，在打包项目生成配置说明文件spring-configuration-metadata.json时，可能会丢失泛型）

   如上面的：FileTypeMapping就不是内部类

5. 叶子节点字段上要写javadoc

   在配置文件中编写或查看对应配置时，如果有javadoc的话，IDE会自动将该javadoc提示给开发者

   如上面的：SecurityScheme#schemeName、SecurityScheme#headerKey、SecurityScheme#scheme、SecurityScheme#bearerFormat

相关链接

• notebook笔记