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

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表格進行配置上的理解。

名稱	類型	目的
name	String	屬性的全名。名稱採用小寫的週期分隔形式(例如server.address)。此屬性是強制性的。
type	String	屬性的數據類型的完整簽名（例如java.lang.String），但也是完整的泛型類型（例如java.util.Map<java.util.String,acme.MyEnum>）。您可使用此屬性來指導用戶能夠輸入的值的類型。爲了保持一致性，經過使用其包裝對應項（例如，boolean變爲java.lang.Boolean）來指定基元的類型。請注意，此類多是一個複雜類型，它從Stringas綁定的值轉換而來。若是類型未知，則能夠省略。
description	String	能夠向用戶顯示的組的簡短描述。若是沒有可用的描述，則能夠省略。建議描述爲簡短段落，第一行提供簡明摘要。描述中的最後一行應以句點（.）結尾。
sourceType	String	貢獻此屬性的源的類名稱。例如，若是屬性來自帶註釋的類@ConfigurationProperties，則此屬性將包含該類的徹底限定名稱。若是源類型未知，則能夠省略。
defaultValue	Object	默認值，若是未指定屬性，則使用該值。若是屬性的類型是數組，則它能夠是值數組。若是默認值未知，則能夠省略。

deprecation每一個properties元素的屬性中包含的JSON對象能夠包含如下屬性：

名稱	類型	目的
level	String	棄用級別，能夠是warning（默認）或error。當屬性具備warning棄用級別時，它仍應綁定在環境中。可是，當它具備error棄用級別時，該屬性再也不受管理且不受約束。
reason	String	該屬性被棄用的緣由的簡短描述。若是沒有可用的緣由，能夠省略。建議描述爲簡短段落，第一行提供簡明摘要。描述中的最後一行應以句點（.）結尾。
replacement	String	替換此不推薦使用的屬性的屬性的全名。若是此屬性沒有替換，則能夠省略。

對應的@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