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