JSON Schemaからドキュメントを生成するソフトウェアまとめ

JSON Schemaを作らなければと思っても、つい面倒で先送りにしてしまいがちです。単なるシステム上だけでなく副次的に開発補助の仕組みがあれば、作る意欲もわくでしょう。そこで今回はJSON Schemaファイルを読み込んでAPIドキュメントを生成してくれるソフトウェアを紹介します。

node.jsとredisの組み合わせで動作します。JSON Schemaファイルを置いておくと、その内容をHTML上に整形して表示してくれます。Webブラウザ上から実際にAPIをコールすることもできるようになっています。

maticはnode.jsで作られているコマンドで、特定のフォルダとディレクトリの配置によってJSON SchemaをHTMLドキュメント化します。

JSON Schemaに対してXSLスタイルシートを適用することでHTML化するという試みです。今はJSONを一旦XML化し、その後XSLスタイルシートを適用します。

PrmdはRubyのライブラリで、HTMLではなくMarkdownドキュメントを出力します。JSON Schemaファイルが複数に分かれていても扱えるので、大型化しても運用しやすそうです。

JdocもRubyのライブラリで、YAMLファイルに定義した内容からAPIドキュメントを生成できるようになっています。

JSON Schemaをドキュメント化すると言うよりも、構造をHTMLを使って見やすくしてくれるツールと言った感じのソフトウェアです。Swagger向けにAPIドキュメントとして生成する機能もあります。

今回紹介したソフトウェアを使うことでAPIドキュメントを作成するコストが大幅に下がるようになります。システムとドキュメントの乖離が避けられればメンテナンスコストも低くなるでしょう。ぜひJSON Schemaを用いた開発の際に使ってみてください。