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

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

ConfigurationProperties与NestedConfigurationProperty

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

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

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

ConfigurationProperties使用案例说明

假设你的配置类是这样的

java 复制代码
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

是这样的

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

相关链接

相关推荐
牧瀬クリスだ20 小时前
从零手写博客系统:分层架构与统一响应(一)
java·数据库·架构·mybatis·springboot·安全架构
这个昵称不容易2 天前
SpringBoot 购物推荐网站的设计与实现:120 个 Java 文件、147 个接口、13 张表,附真实运行截图
java·springboot·毕设
隔窗听雨眠3 天前
Spring Boot启动提速的机制剖析与调优路径
性能优化·springboot·后端开发
这个昵称不容易3 天前
SpringBoot 医疗病历交互系统的设计与实现:192 个 Java 文件、256 个接口、22 张表,附真实运行截图
java·springboot·毕设
这个昵称不容易4 天前
SpringBoot 医疗病历交互系统毕设:192 个 Java 文件、256 个接口、22 张表,附真实运行截图
java·springboot·毕设
瑞雪兆丰年兮7 天前
JavaWeb-day13-SpringBootWeb事务管理&AOP
java·开发语言·springboot·javaweb·事务·web·aop
这个昵称不容易9 天前
考试报名系统的设计与实现(SpringBoot + MySQL + Vue 三角色平台)
java·springboot·毕设
欢醉9 天前
SpringBoot中@Async异步透传问题内部分享
springboot·springcloud·asynctask异步更新
小南家的青蛙10 天前
基于Spring Boot 2.x开发的微服务访问Redis的方案
redis·springboot
这个昵称不容易10 天前
旅游管理系统的设计与实现(SpringBoot + MySQL + Vue 前后端分离)
java·springboot·毕设