Help us understand the problem. What is going on with this article?

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

More than 5 years have passed since last update.

さいきん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を使い続けるのもいいですが、こうした支援ツールも一度検討してみてはどうでしょうか。

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away