
# JSON Schemas

`/actuator/jsonschemas` は、アプリケーションの JSON Schema を表示します。レジストリが持つスキーマと、すべての `@Introspected` クラスのスキーマです。Spring Boot にこのようなエンドポイントはありません。

## 使う理由

「このサービスはどんな JSON を受け取り、返すのか?」には、スキーマが答えます。動作中のアプリケーションは、自分のクラスからそれを書き出せます。クライアントのチームは、呼び出すサービスから `Order` のスキーマを取得でき、デプロイされたビルドが実際にどのスキーマを持っているか (`spring.json.schemas` のもの、独自のカスタマイザーのもの) も確認できます。

## 例

```properties
# lib/resources/application.properties
management.endpoints.web.exposure.include=health,jsonschemas
```

```console
$ curl localhost:8080/actuator/jsonschemas
```

```json
{"registry": {
   "resources:schemas/order.json": {"type": "object", "...": "..."}},
 "introspected": {
   "Book": {"$schema": "https://json-schema.org/draft/2020-12/schema",
            "title": "Book", "type": "object", "...": "..."}}}
```

クラス名または location で一つのスキーマを取得します。

```console
$ 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](../spring-core-dart/json/json-schema.md) にあります。

## 一つのスキーマ

`GET /actuator/jsonschemas/{name}` は一つのスキーマを返します。name はまずクラス名として、次にレジストリの location として探されます (`jsonschemas/` の後のセグメントは `/` でつながれるので、スラッシュを含む location も使えます)。一致するものがなければ `404` を返します。

## 公開

このエンドポイントはデフォルトで有効ですが、`health` 以外のすべてのエンドポイントと同じく、HTTP では公開されません。`management.endpoints.web.exposure.include` に `jsonschemas` を追加するか、`*` を使ってください。

```properties
management.endpoints.web.exposure.include=health,jsonschemas
```

スキーマはデータの形とアプリケーションが読み込む場所を示すので、エンドポイントを保護してください ([セキュリティ](security.md) を参照)。`management.endpoint.jsonschemas.access=none` で無効にできます。

## Spring (Java) との対応

Spring Boot Actuator に相当するものはありません。Java ではライブラリ (Jackson の `jsonSchema` モジュール、victools の `jsonschema-generator`) がスキーマを書き、アプリケーションがそれを手で提供します。

## 関連項目

- [エンドポイント](endpoints.md)
- [セキュリティ](security.md)
- [JSON Schema](../spring-core-dart/json/json-schema.md)
- [JSON Schema の Bean](../spring-boot-dart/json-schema.md)
