APIドキュメントを書くのが楽になるツールまとめ

  • 1088
    いいね
  • 0
    コメント
この記事は最終更新日から1年以上が経過しています。

さいきん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コールを試すことができる点。

1387628508.png

様々な言語のWAFに対応したライブラリも開発されてる。
Home · wordnik/swagger-core Wiki

iodocs

mashery/iodocs

node.jsで動作するドキュメントツール。API概要の定義はjsonで記述するようになっていて、こちらもswaggerと同様にページ上でAPIコールを試せるようになっている。iodocsに関しては最近postしたのでこちらもどうぞ。
iodocsで便利なREST APIドキュメントを作成する - Qiita [キータ]

iodocs-screen.png

autodoc

r7kamura/autodoc

APIのテストケースからドキュメントを自動生成してくれる。Markdownで出力してくれるので、別途Webサーバを起動する必要とかも無し。

RESTdoclet

RESTdoclet by IG-Group

JavaでSpringMVCな環境で使うツール。Mavenプラグインとして提供されている。ドキュメント生成にはJavadocやSpringのRequestMapping等のアノテーションを利用するので、生成のために余計なアノテーション等をコードに書かなくていいのが特徴的。

carte

devo-ps/carte
デモ: Carte

Markdownでドキュメント記述ができる。Jekyllベース。swaggerやiodocsと比較してシンプルな作りになっており、APIコールを試す機能は無い。

1387628935.png

まとめ

この手の自動生成や効率化はやり方が沢山ある分、各ツールそれぞれのアプローチが見えて面白いなーと思いました。まだまだ開発途中のものもあり、ちょっと試してて不便に感じる所もあったのですが今後に期待。

wikiやGithub READMEを使い続けるのもいいですが、こうした支援ツールも一度検討してみてはどうでしょうか。

この投稿は ドキュメンテーション Advent Calendar 201321日目の記事です。