Bean 検証制約
Spring REST Docs は、制約をドキュメント化するのに役立つ多くのクラスを提供します。ConstraintDescriptions のインスタンスを使用して、クラスの制約の説明にアクセスできます。次の例は、その方法を示しています。
import java.util.List;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import org.springframework.restdocs.constraints.ConstraintDescriptions;
class Constraints {
List<String> describeNameConstraints() {
ConstraintDescriptions userConstraints = new ConstraintDescriptions(UserInput.class); (1)
return userConstraints.descriptionsForProperty("name"); (2)
}
static class UserInput {
@NotNull
@Size(min = 1)
String name;
@NotNull
@Size(min = 8)
String password;
}
}| 1 | UserInput クラスの ConstraintDescriptions のインスタンスを作成します。 |
| 2 | name プロパティの制約の説明を取得します。このリストには、NotNull 制約と Size 制約の 2 つの説明が含まれています。 |
Spring HATEOAS サンプルの ApiDocumentation [GitHub] (英語) クラスは、この機能の動作を示しています。
制約を見つける
デフォルトでは、制約は Bean 検証 Validator を使用して検出されます。現在、プロパティ制約のみがサポートされています。カスタム ValidatorConstraintResolver インスタンスで ConstraintDescriptions を作成することにより、使用される Validator をカスタマイズできます。制約解決を完全に制御するには、独自の ConstraintResolver 実装を使用できます。
制約の記述
すべての Bean 検証 3.1 の制約について、デフォルトの説明が提供されています。
AssertFalseAssertTrueDecimalMaxDecimalMinDigitsEmailFutureFutureOrPresentMaxMinNegativeNegativeOrZeroNotBlankNotEmptyNotNullNullPastPastOrPresentPatternPositivePositiveOrZeroSize
Hibernate Validator からの次の制約について、デフォルトの説明も提供されます。
CodePointLengthCreditCardNumberCurrencyEANEmailLengthLuhnCheckMod10CheckMod11CheckNotBlankNotEmptyCurrencyRangeSafeHtmlURL
デフォルトの説明をオーバーライドするか、新しい説明を提供するために、ベース名 org.springframework.restdocs.constraints.ConstraintDescriptions でリソースバンドルを作成できます。Spring HATEOAS ベースのサンプルには、このようなリソースバンドルの例 [GitHub] (英語) が含まれています。
リソースバンドル内の各キーは、制約の完全修飾名と .description です。例: 標準の @NotNull 制約のキーは jakarta.validation.constraints.NotNull.description です。
説明で制約の属性を参照するプロパティプレースホルダーを使用できます。例: @Min 制約のデフォルトの説明である Must be at least ${value} は、制約の value 属性を参照しています。
制約記述の解決をより詳細に制御するには、カスタム ResourceBundleConstraintDescriptionResolver を使用して ConstraintDescriptions を作成できます。完全に制御するために、カスタム ConstraintDescriptionResolver 実装で ConstraintDescriptions を作成できます。
生成されたスニペットでの制約の説明の使用
制約の説明ができたら、生成されたスニペットで好きなように自由に使用できます。例: フィールドの説明の一部として制約の説明を含めたい場合があります。または、リクエストフィールドスニペットに追加情報として制約を含めることもできます。Spring HATEOAS ベースのサンプルの ApiDocumentation [GitHub] (英語) クラスは、後者のアプローチを示しています。
