JSON Schemas
/actuator/jsonschemas は、アプリケーションの JSON Schema を表示します。レジストリが持つスキーマと、すべての @Introspected クラスのスキーマです。Spring Boot にこのようなエンドポイントはありません。
使う理由
「このサービスはどんな JSON を受け取り、返すのか?」には、スキーマが答えます。動作中のアプリケーションは、自分のクラスからそれを書き出せます。クライアントのチームは、呼び出すサービスから Order のスキーマを取得でき、デプロイされたビルドが実際にどのスキーマを持っているか (spring.json.schemas のもの、独自のカスタマイザーのもの) も確認できます。
例
# lib/resources/application.properties
management.endpoints.web.exposure.include=health,jsonschemas
$ curl localhost:8080/actuator/jsonschemas
{"registry": {
"resources:schemas/order.json": {"type": "object", "...": "..."}},
"introspected": {
"Book": {"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Book", "type": "object", "...": "..."}}}
クラス名または location で一つのスキーマを取得します。
$ curl localhost:8080/actuator/jsonschemas/Book
$ curl localhost:8080/actuator/jsonschemas/resources:schemas/order.json
列挙されるもの
| キー | 内容 |
|---|---|
registry |
コンテキストの JsonSchemaRegistry のスキーマ。それぞれ、知られている location または $id をキーにします。spring.json.schemas、@JsonSchemaSource、JsonSchema の Bean、独自の JsonSchemaRegistryCustomizer の Bean のものです |
introspected |
アプリケーションのすべての @Introspected クラスのスキーマ。クラス名をキーにし、イントロスペクションから ObjectMapper の命名で作られます。その JSON の見た目です |
- レジストリの Bean がなければ、
registryは空です。 introspectedは enum とジェネリッククラスを除き、同じ名前のクラスが二つあれば最初のものを持ちます。スキーマが記述するものと記述しないもの (ポリモーフィズム、@JsonUnwrapped) は JSON Schema にあります。
一つのスキーマ
GET /actuator/jsonschemas/{name} は一つのスキーマを返します。name はまずクラス名として、次にレジストリの location として探されます (jsonschemas/ の後のセグメントは / でつながれるので、スラッシュを含む location も使えます)。一致するものがなければ 404 を返します。
公開
このエンドポイントはデフォルトで有効ですが、health 以外のすべてのエンドポイントと同じく、HTTP では公開されません。management.endpoints.web.exposure.include に jsonschemas を追加するか、* を使ってください。
management.endpoints.web.exposure.include=health,jsonschemas
スキーマはデータの形とアプリケーションが読み込む場所を示すので、エンドポイントを保護してください (セキュリティ を参照)。management.endpoint.jsonschemas.access=none で無効にできます。
Spring (Java) との対応
Spring Boot Actuator に相当するものはありません。Java ではライブラリ (Jackson の jsonSchema モジュール、victools の jsonschema-generator) がスキーマを書き、アプリケーションがそれを手で提供します。