この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。
JSON Refs Atom Package
現在進行中のプロジェクトで、 Swagger を使って REST API 仕様書を作成しています。 実際のプロジェクトで作成する Swagger はとても巨大で、1ファイルで管理するのは難しいです。 そこで考えるのがファイルの分割。以下の記事でも紹介していますが、swagger.json のファイルを分割して 作成・管理することができます。実際に使用するときは、外部参照の定義を解決して swagger.json を作成します。
JSON 内で $ref
を使用して、他で定義されている JSON を参照する JSON Reference という規格があったので、調べがてら Atom の Package にして公開しました。(正直役に立つかどうかわかりません。。)
インストール
※ このパッケージは、Atom エディタのプラグインとして動作します。Atom をまだインストールしていない場合は、ここからダウンロードしてインストールしてください。
json-refs は以下の手順でインストール出来ます。
apm install json-refs
または
Settings/Preferences ➔ Install ➔ Search for json-refs
使い方
1. JSON ファイルの作成
Atom エディタを起動して、以下の内容で sample.json
という名前で保存します。
{
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"street_address",
"city",
"state"
]
}
},
"type": "object",
"properties": {
"billing_address": {
"$ref": "#/definitions/address"
},
"shipping_address": {
"allOf": [
{
"$ref": "#/definitions/address"
},
{
"properties": {
"type": {
"enum": [
"residential",
"business"
]
}
},
"required": [
"type"
]
}
]
}
}
}
上記のサンプルは、1ファイル内に定義と参照が入っているサンプルです。
definitions
内に address オブジェクトのスキーマが定義されています。
また、billing_address
や shipping_address
で、definitions で定義されている address を参照しています。
2. $ref で参照している内容を解決する
Atom のコマンドパレットを表示して、Json Refs: Resolve
を実行してください。
以下はその実行結果です。
{
"definitions": {
"address": {
"type": "object",
"properties": {
"street_address": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"street_address",
"city",
"state"
]
}
},
"type": "object",
"properties": {
"billing_address": {
"type": "object",
"properties": {
"street_address": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"street_address",
"city",
"state"
]
},
"shipping_address": {
"allOf": [
{
"type": "object",
"properties": {
"street_address": {
"type": "string"
},
"city": {
"type": "string"
},
"state": {
"type": "string"
}
},
"required": [
"street_address",
"city",
"state"
]
},
{
"properties": {
"type": {
"enum": [
"residential",
"business"
]
}
},
"required": [
"type"
]
}
]
}
}
}
billing_address など、$ref で参照していた内容が実体の内容に解決されています。
さいごに
今回は、swagger.json を作成する際に、JSON の外部参照の規格を知るきっかけになりました。規格を調べてみて REST API の レスポンスにもこの規格を使って、外部リソースの情報を付加する目的で使っても便利そうだなと感じました(一般的かどうかは別として)。また、複雑なリレーショナルデータベースのテーブルの内容を Elasticsearch へインデックスする際にも利用できると、これもまた便利そうです。(Ingest あたりに JSON Reference パーサが実装されると Index データ作成が便利かな?)
ソースコードは GitHub で公開していますので、追加機能などプルリクお待ちしています。 https://github.com/KunihikoKido/atom-json-refs