springboot 之 additional-spring-configuration-metadata.json 自定义提示

简介

additional-spring-configuration-metadata.json、spring-configuration-metadata.json在 springboot-starter 官方项目或第三方 starter 项目中随处可见，那它起的作用是什么？让我们一起探讨一下。

官方文章

官方一篇文章很详细讲解了 Configuration Metadata 的作用。
有兴趣的小伙伴可以查看下(配置元数据)。

Configuration Metadata

Appendix B. Configuration Metadata
Spring Boot jars include metadata files that provide details of all supported configuration properties. The files are designed to let IDE developers offer contextual help and“code completion”as users are working with application.properties or application.yml files.

The majority of the metadata file is generated automatically at compile time by processing all items annotated with @ConfigurationProperties. However, it is possible to write part of the metadata manually for corner cases or more advanced use cases.

简介说明配置 additional-spring-configuration-metadata.json 文件后，在开发人员的 IDE 工具使用个人编写的配置读取很有效的在 application.properties 或application.yml文件下完成提示。

使用

1. 元数据格式

配置元数据文件位于 jar 下面。META-INF/spring-configuration-metadata.json它们使用简单的 JSON 格式，其中的项目分类在“groups”或“properties”下，其他值提示分类在“hints”下，如下例所示：

{"groups": [
    {
        "name": "server",
        "type": "org.springframework.boot.autoconfigure.web.ServerProperties",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    }
    ...
],"properties": [
    {
        "name": "server.port",
        "type": "java.lang.Integer",
        "sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
    }
    ...
],"hints": [
    {
        "name": "spring.jpa.hibernate.ddl-auto",
        "values": [
            {
                "value": "none",
                "description": "Disable DDL handling."
            },
            {
                "value": "validate",
                "description": "Validate the schema, make no changes to the database."
            }
        ]
    }
]}

2.properties提示编写

当然了我们需要编写 META-INF/additional-spring-configuration-metadata.json 进行拓展。

下面简单创建一个 starter 使用 additional-spring-configuration-metadata.json 进行提示。

在 resources/META-INF 目录下创建additional-spring-configuration-metadata.json

内容大致如下:

{"properties": [
    {
      "name": "swagger.basePackage",
      "type": "java.lang.String",
      "description": "文档扫描包路径。"
    },
    {
      "name": "swagger.title",
      "type": "java.lang.String",
      "defaultValue": "平台系统接口详情",
      "description": "title 如: 用户模块系统接口详情。"
    },
    {
      "name": "swagger.description",
      "type": "java.lang.String",
      "defaultValue": "在线文档",
      "description": "服务文件介绍。"
    },
    {
      "name": "swagger.termsOfServiceUrl",
      "type": "java.lang.String",
      "defaultValue": "https://www.test.com/",
      "description": "服务条款网址。"
    },
    {
      "name": "swagger.version",
      "type": "java.lang.String",
      "defaultValue": "V1.0",
      "description": "版本。"
    }
]}

大家参考下面 properties 表格进行配置上的理解。

deprecation每个 properties 元素的属性中包含的 JSON 对象可以包含以下属性：

对应的 @ConfigurationProperties 类如下:

@Data
@ConfigurationProperties(SwaggerProperties.PREFIX)
public class SwaggerProperties {

  public static final String PREFIX = "swagger";

  /**
   * 文档扫描包路径
   */
  private String basePackage = "";

  /**
   * title 如: 用户模块系统接口详情
   */
  private String title = "平台系统接口详情";

  /**
   * 服务文件介绍
   */
  private String description = "在线文档";

  /**
   * 服务条款网址
   */
  private String termsOfServiceUrl = "https://www.test.com/";

  /**
   * 版本
   */
  private String version = "V1.0";

}

现在就可以在 application.properties 文件里尝试提示。

总结

当然了，这个只是实现了简单的配置提示功能，其他的功能大家可以再次产考 (配置元数据) 文章进行学习。

示例代码地址: swagger-spring-boot