メタデータ形式

構成メタデータファイルは、META-INF/spring-configuration-metadata.json の jar 内にあります。次の例に示すように、項目は「グループ」または「プロパティ」に分類され、追加の値のヒントは「ヒント」に分類され、無視される項目は「無視」に分類される JSON 形式を使用します。

{"groups": [
	{
		"name": "server",
		"type": "org.springframework.boot.autoconfigure.web.ServerProperties",
		"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
	},
	{
		"name": "spring.jpa.hibernate",
		"type": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate",
		"sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties",
		"sourceMethod": "getHibernate()"
	}
	...
],"properties": [
	{
		"name": "server.port",
		"type": "java.lang.Integer",
		"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
	},
	{
		"name": "server.address",
		"type": "java.net.InetAddress",
		"sourceType": "org.springframework.boot.autoconfigure.web.ServerProperties"
	},
	{
		  "name": "spring.jpa.hibernate.ddl-auto",
		  "type": "java.lang.String",
		  "description": "DDL mode. This is actually a shortcut for the \"hibernate.hbm2ddl.auto\" property.",
		  "sourceType": "org.springframework.boot.autoconfigure.orm.jpa.JpaProperties$Hibernate"
	}
	...
],"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."
			},
			{
				"value": "update",
				"description": "Update the schema if necessary."
			},
			{
				"value": "create",
				"description": "Create the schema and destroy previous data."
			},
			{
				"value": "create-drop",
				"description": "Create and then destroy the schema at the end of the session."
			}
		]
	}
	...
],"ignored": {
	"properties": [
		{
			"name": "server.ignored"
		}
		...
	]
}}

各「プロパティ」は、ユーザーが指定された値で指定する構成アイテムです。例: server.port および server.address は、次のように application.properties/application.yaml で指定される場合があります。

  • プロパティ

  • YAML

server.port=9090
server.address=127.0.0.1
server:
  port: 9090
  address: 127.0.0.1

「グループ」は、それ自体が値を指定するのではなく、プロパティのコンテキストグループを提供する上位レベルのアイテムです。例: server.port および server.address プロパティは server グループの一部です。

すべての「プロパティ」に「グループ」がある必要はありません。一部のプロパティはそれ自体で存在する場合があります。

「ヒント」は、特定のプロパティを構成する際にユーザーを支援するために使用される追加情報です。例: 開発者が spring.jpa.hibernate.ddl-auto プロパティを構成する場合、ツールはヒントを使用して、none、validate、update、create、create-drop 値の自動補完ヘルプを提供できます。

最後に、「無視」は意図的に無視された項目です。このセクションの内容は通常、追加メタデータから取得されます。

グループ属性

groups 配列に含まれる JSON オブジェクトには、次の表に示す属性を含めることができます。

名前 タイプ 目的

name

String

グループのフルネーム。この属性は必須です。

type

String

グループのデータ型のクラス名。例: グループが @ConfigurationProperties (Javadoc) でアノテーションされたクラスに基づいている場合、属性にはそのクラスの完全修飾名が含まれます。@Bean (Javadoc) メソッドに基づいている場合は、そのメソッドの戻り値の型になります。型が不明な場合は、属性を省略できます。

description

String

ユーザーに表示できるグループの簡単な説明。説明がない場合は、省略できます。説明は短いパラグラフにすることをお勧めします。最初の行は簡潔な要約を提供します。説明の最後の行はピリオド（.）で終わる必要があります。

sourceType

String

このグループに貢献したソースのクラス名。例: グループが @ConfigurationProperties (Javadoc) でアノテーションが付けられた @Bean (Javadoc) メソッドに基づいている場合、この属性にはメソッドを含む @Configuration (Javadoc) クラスの完全修飾名が含まれます。ソース型が不明な場合は、属性を省略できます。

sourceMethod

String

このグループに貢献したメソッドの完全な名前 (括弧と引数の型を含む) (たとえば、@ConfigurationProperties (Javadoc) アノテーション付き @Bean (Javadoc) メソッドの名前)。ソースメソッドが不明な場合は省略できます。

プロパティ属性

properties 配列に含まれる JSON オブジェクトには、次の表で説明する属性を含めることができます。

名前 タイプ 目的

name

String

プロパティの完全な名前。名前は小文字のピリオド区切り形式です（たとえば、server.address）。この属性は必須です。

type

String

プロパティのデータ型の完全なシグネチャー (例: String (標準 Javadoc) ) だけでなく、完全なジェネリクス型 (例: java.util.Map<java.lang.String,com.example.MyEnum>) もあります。この属性を使用して、ユーザーが入力できる値の型をガイドできます。一貫性を保つために、プリミティブの型は、対応するラッパーを使用して指定されます (例: boolean は Boolean (標準 Javadoc) になります)。このクラスは、値がバインドされるときに String (標準 Javadoc) から変換される複合型である可能性があることに注意してください。型が不明な場合は省略できます。

description

String

ユーザーに表示できるプロパティの簡単な説明。説明がない場合は、省略できます。説明は短いパラグラフにすることをお勧めします。最初の行は簡潔な要約を提供します。説明の最後の行はピリオド（.）で終わる必要があります。

sourceType

String

このプロパティを提供したソースのクラス名。例: プロパティが @ConfigurationProperties (Javadoc) でアノテーションが付けられたクラスのものである場合、この属性にはそのクラスの完全修飾名が含まれます。ソース型が不明な場合は省略できます。

defaultValue

オブジェクト

デフォルト値。プロパティが指定されていない場合に使用されます。プロパティの型が配列の場合、値の配列にすることができます。デフォルト値が不明な場合、省略できます。

deprecation

使用すべきではない

プロパティが廃止されるかどうかを指定します。フィールドが非推奨でない場合、またはその情報が不明な場合は、省略できます。次の表に、deprecation 属性に関する詳細を示します。

各 properties 要素の deprecation 属性に含まれる JSON オブジェクトには、次の属性を含めることができます。

名前 タイプ 目的

level

String

非推奨のレベル。warning （デフォルト）または error のいずれかです。プロパティに warning 非推奨レベルがある場合でも、環境内でバインドする必要があります。ただし、error 非推奨レベルがある場合、プロパティは管理されなくなり、バインドされません。

reason

String

プロパティが廃止された理由の簡単な説明。理由がない場合は、省略できます。説明は短いパラグラフにすることをお勧めします。最初の行は簡潔な要約を提供します。説明の最後の行はピリオド（.）で終わる必要があります。

replacement

String

この廃止されたプロパティを置き換えるプロパティの完全な名前。このプロパティの代替がない場合は、省略できます。

since

String

プロパティが非推奨になったバージョン。省略可能です。

Spring Boot 1.3 以前は、deprecation 要素の代わりに単一の deprecated ブール属性を使用できました。これは現在も非推奨の方法でサポートされており、今後は使用しないでください。理由と置換がない場合は、空の deprecation オブジェクトを設定する必要があります。

非推奨は、非推奨のプロパティを公開する getter に @DeprecatedConfigurationProperty (Javadoc) アノテーションを追加することで、コード内で宣言的に指定することもできます。たとえば、my.app.target プロパティがわかりにくいため、my.app.name に名前が変更されたとします。次の例は、その状況を処理する方法を示しています。

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.boot.context.properties.DeprecatedConfigurationProperty;

@ConfigurationProperties("my.app")
public class MyProperties {

	private String name;

	public String getName() {
		return this.name;
	}

	public void setName(String name) {
		this.name = name;
	}

	@Deprecated
	@DeprecatedConfigurationProperty(replacement = "my.app.name")
	public String getTarget() {
		return this.name;
	}

	@Deprecated
	public void setTarget(String target) {
		this.name = target;
	}

}
level を設定する方法はありません。コードがまだプロパティを処理しているため、warning が常に想定されます。

上記のコードは、廃止されたプロパティが引き続き機能することを確認します（バックグラウンドで name プロパティに委譲します）。getTarget および setTarget メソッドがパブリック API から削除されると、メタデータの自動非推奨ヒントもなくなります。ヒントを保持したい場合は、error 非推奨レベルの手動メタデータを追加することで、ユーザーにそのプロパティについての情報を確実に提供できます。これは、replacement が提供されている場合に特に役立ちます。

ヒント属性

hints 配列に含まれる JSON オブジェクトには、次の表に示す属性を含めることができます。

名前 タイプ 目的

name

String

このヒントが参照するプロパティの完全な名前。名前は小文字のピリオド区切り形式です（spring.mvc.servlet.path など）。プロパティがマップ（system.contexts など）を参照している場合、ヒントはマップのキー（system.contexts.keys）またはマップの値（system.contexts.values）に適用されます。この属性は必須です。

values

ValueHint[]

ValueHint オブジェクトで定義されている有効な値のリスト（次の表で説明）。各エントリは値を定義し、説明が含まれる場合があります。

providers

ValueProvider[]

ValueProvider オブジェクトによって定義されたプロバイダーのリスト（このドキュメントで後述）。各エントリは、プロバイダーの名前とそのパラメーター（存在する場合）を定義します。

各 hint 要素の values 属性に含まれる JSON オブジェクトには、次の表で説明する属性を含めることができます。

名前 タイプ 目的

value

オブジェクト

ヒントが参照する要素の有効な値。プロパティの型が配列の場合、値の配列にすることもできます。この属性は必須です。

description

String

ユーザーに表示できる値の簡単な説明。説明がない場合は、省略できます。説明は短いパラグラフにすることをお勧めします。最初の行は簡潔な要約を提供します。説明の最後の行はピリオド（.）で終わる必要があります。

各 hint 要素の providers 属性に含まれる JSON オブジェクトには、次の表で説明する属性を含めることができます。

名前 タイプ 目的

name

String

ヒントが参照する要素に追加のコンテンツ支援を提供するために使用するプロバイダーの名前。

parameters

JSON オブジェクト

プロバイダーがサポートする追加パラメーター（詳細については、プロバイダーのドキュメントを確認してください）。

無視される属性

ignored オブジェクトには、次の表に示す属性を含めることができます。

名前 タイプ 目的

properties

アイテム無視 []

ItemIgnore オブジェクトによって定義される無視されるプロパティのリスト (次の表で説明)。各エントリは、無視されるプロパティの名前を定義します。

各 ignored 要素の properties 属性に含まれる JSON オブジェクトには、次の表で説明する属性を含めることができます。

名前 タイプ 目的

name

String

無視するプロパティの完全な名前。名前は小文字のピリオドで区切られた形式です (例: spring.mvc.servlet.path)。この属性は必須です。

繰り返されるメタデータアイテム

同じ「プロパティ」および「グループ」名を持つオブジェクトは、メタデータファイル内に複数回表示される場合があります。例: 2 つの別々のクラスを同じプレフィックスにバインドし、それぞれがプロパティ名を重複させる可能性があります。メタデータに同じ名前が複数回現れることは一般的ではありませんが、メタデータの利用者はそれをサポートするよう注意する必要があります。