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

justry_deng

于 2024-09-09 13:32:45 发布

阅读量540

点赞数 14

分类专栏： Java知识大杂烩文章标签：美化配置配置报黄配置说明 springboot 配置规范化

本文链接：https://blog.csdn.net/justry_deng/article/details/142056529

版权

Java知识大杂烩专栏收录该内容

81 篇文章 194 订阅

订阅专栏

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

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】是不符合预期的，它丢失了泛型，这就导致：你在写配置文件时，你的配置会报黄，虽然功能使用上没影响

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

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

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

如上面的：SecurityScheme、Info
如果字段是一个简单类，那这个简单类可以是正常类、也可以是内部类，都无所谓

如上面的：SecurityScheme、Info
如果字段是一个嵌套复杂类，那么不需要标@NestedConfigurationProperty

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

如上面的：FileTypeMapping就不是内部类
叶子节点字段上要写javadoc

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

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