メタデータ形式

構成メタデータファイルは 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."
			}
		]
	}
]}

各「プロパティ」は、ユーザーが指定された値で指定する構成アイテムです。例: 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 アノテーションが付けられたクラスに基づいている場合、属性にはそのクラスの完全修飾名が含まれます。@Bean メソッドに基づいている場合、そのメソッドの戻り値の型になります。型が不明な場合、属性は省略できます。

description

String

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

sourceType

String

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

sourceMethod

String

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

プロパティ属性

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

名前 タイプ 目的

name

String

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

type

String

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

description

String

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

sourceType

String

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

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 アノテーションを追加することにより、コードで宣言的に指定することもできます。たとえば、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 オブジェクト

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

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

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