2017-11-20

$ref のJSON Pointerを展開するrubygemを書いた

JSON Schemaで記述される$refパラメータのリンクを展開するrubygemを書きました。

committeeでOpenAPI 2を使う場合、paramters等の一部の属性に含まれる$refパラメータを展開しないことがわかったので、事前にJSONを展開するライブラリが欲しかった、というのがモチベーションです。

json-refという同様のrubygemは既に存在するのですがそのままでは利用できずリポジトリ自体もアクティブではないように見受けられたので新たにgemをリリースしました。forkしてGemfileにgithubのリポジトリを指定して使う方法もあったのですが、デプロイするのにgitが必要なのどうだろ、と思ったのでrubygemで公開した感じです。まぁcapistranoとか実行するときはgit有るし大抵の場合問題ないんですが…

使い方

Gemfileにはこんな感じで
gem 'json_refs'

ハッシュに対してJsonRefs.callを呼びだせば$refのプロパティをよしなに展開します。

json = { 'a' => 'foo', 'b' => { '$ref' => '#/a' } }
JsonRefs.(json) # {"a"=>"foo", "b"=>"foo"}

リモートのファイルも取得できます。

json = { 'remote_path' => { '$ref' => 'https://httpbin.org/user-agent' } }
JsonRefs.(json) # {"remote_path"=> { "user-agent" => "Ruby"}}

YAMLもいけます。

json = { 'yaml_file' => { '$ref' => '/path/to/file.yaml' } }
JsonRefs.(json) # {"yaml_file"=> { "attr" => "value" }}

YAMLを展開できるので、OpenAPIのドキュメントをYAMLで書きつつ複数ファイルに分割して、実行時に一つのハッシュに結合させることもできます。index的なメインのYAMLをJsonRefsに読み込ませて結合し、さらに展開したい場合はその結合したハッシュをJsonRefsにかければ良いです。

なので、OpenAPIのドキュメントを複数ファイルに分割して管理するのは、json-refsなどのNodeJSのライブラリを使わずにできるので全てRubyで完結します。

このエントリーをはてなブックマークに追加