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 の見た目です

一つのスキーマ

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) がスキーマを書き、アプリケーションがそれを手で提供します。

関連項目