Jdoc - JSON SchemaからAPIドキュメントを生成
JSONがWeb APIのデータ送受信フォーマットとして活用されるようになると、受け取る側と発信する側でその内容が適切であるかどうか検証する手段が必要になります。それがJSON Schemaです。 2009年頃に登場したようですが、当時は面倒がってあまり使われてきませんでしたが、JSONの普及ともとに注目が集まっています。そんなJSON Schemaを開発者にも優しいフォーマットに変換してくれるのがJdocです。
Jdocの使い方
JdocはRubygemsからインストールできます。
$ gem install jdoc
使い方としてはjdocコマンドにスキーマのパスを渡すだけです。
$ jdoc spec/fixtures/schema.yml
# Example API
* [App](#app)
* [GET /apps](#get-apps)
* [POST /apps](#post-apps)
* [GET /apps/:id](#get-appsid)
* [PATCH /apps/:id](#patch-appsid)
* [DELETE /apps/:id](#delete-appsid)
## App
An app is a program to be deployed.
:
例えばこんな感じにMarkdownフォーマットのファイルができます。
これならプログラマにとっても分かりやすいですよね。そして開発したらスキーマとあわせてデータの検証ができ、動作確認ができます。さらにJSON Schema関連のツールは多数出てきており、モックサーバを立てたり、クライアントのコードを生成してくれるといったものもあります。JSON Schemaを使うことでシステムにもプログラマにも優しいツールが出来上がっていくことでしょう。
JdocはRuby製、MIT Licenseのオープンソース・ソフトウェアです。