さいきんREST APIのドキュメントを書いていて、wiki使うのだるいし他に良い方法ないかな〜と調べてた時に見つけたツール群をまとめてみます。
追記: こちらも便利そうなので参考にどうぞ。
REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
swagger
Swagger: A simple, open standard for describing REST APIs with JSON | Reverb for Developers
デモ: Swagger UI
ソースコード中にAPIの概要を書いておくと、それを元にドキュメントを自動生成してくれる。wikiやmarkdownで書くのと決定的な違いは、↓のようにドキュメント上のformからAPIコールを試すことができる点。
様々な言語のWAFに対応したライブラリも開発されてる。
Home · wordnik/swagger-core Wiki
- Scalatra2.2+scalatra-swaggerでREST APIのリファレンスを生成する #1 ｜ Developers.IO
- Scalatra2.2+scalatra-swaggerでREST APIのリファレンスを生成する #2 ｜ Developers.IO
iodocs
node.jsで動作するドキュメントツール。API概要の定義はjsonで記述するようになっていて、こちらもswaggerと同様にページ上でAPIコールを試せるようになっている。iodocsに関しては最近postしたのでこちらもどうぞ。
iodocsで便利なREST APIドキュメントを作成する - Qiita [キータ]
autodoc
APIのテストケースからドキュメントを自動生成してくれる。Markdownで出力してくれるので、別途Webサーバを起動する必要とかも無し。
RESTdoclet
JavaでSpringMVCな環境で使うツール。Mavenプラグインとして提供されている。ドキュメント生成にはJavadocやSpringのRequestMapping等のアノテーションを利用するので、生成のために余計なアノテーション等をコードに書かなくていいのが特徴的。
carte
devo-ps/carte
デモ: Carte
Markdownでドキュメント記述ができる。Jekyllベース。swaggerやiodocsと比較してシンプルな作りになっており、APIコールを試す機能は無い。
まとめ
この手の自動生成や効率化はやり方が沢山ある分、各ツールそれぞれのアプローチが見えて面白いなーと思いました。まだまだ開発途中のものもあり、ちょっと試してて不便に感じる所もあったのですが今後に期待。
wikiやGithub READMEを使い続けるのもいいですが、こうした支援ツールも一度検討してみてはどうでしょうか。