APIドキュメント作成ツールまとめ

まとめというか、ちょいメモ。

API ドキュメント作成を楽にしてくれるツールを探しているんだけどいくつか出てきたので、
とりあえず整理。

おおむねこちらの Qiita の記事で紹介されているツールたち。

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

求めている機能

• 統一されたフォーマットで書けること（Markdown, JSON, YAML, etc.）
• 変更履歴を管理できること
  • GitHub などのバージョン管理システムで使えるとか
• チーム開発で使えること
• コードベースと一緒に管理できること

...などなど。

確認できているツール

この記事で紹介するツールは以下の 5 つ。

• Apiary.io
• Swagger
• I/O Docs
• aglio + api-mock
• （番外編）Postman

このうち、現時点で実際に試せているのは Apiary.io だけです。

Apiary.io

https://apiary.io/

• ドキュメント記述方法
  • API Blueprint という Markdown を拡張した仕様を使って書く
• Pros
  • web サービス上のエディタで記述するだけでなく、GitHub のリポジトリと連携することができる
    • apiary.apib ファイルをコミットすると自動で web 上のドキュメントに反映される
    • private リポジトリとの連携も ◯
  • ドキュメントを定義するだけでモックサーバが作成され、簡単に API コールを試すことができる
    • http://[API ドメイン名].apiary-mock.com という URL でアクセスできるようになる（未確認）
  • 補助ツールが充実
    • vim のシンタックスハイライト
      • GitHub - kylef/apiblueprint.vim: This vim plugin brings syntax highlighting and linting for API Blueprint.
    • CLI
      • GitHub - apiaryio/apiary-client: Apiary CLI client
  • 個人で使う分には無料プランがあるのでフリーで使える
    • チームで使うにはどうしても有料プランになりそう
    • Plans: Free, Standard, and Pro for Developers & Teams | Apiary
• Cons
  • api ドメイン名(*1) に英数字しか使えない（ハイフン使えないので単語で区切れない！）
  • api ドメイン名は世界中で一意になるようにしなければならない
  • 連携した GitHub のリポジトリでドキュメントを管理するには課題が多い
    • ファイルはリポジトリのトップ階層に apiary.apib という名前で用意しないといけない
    • ドキュメントファイルを分割して管理することを（公式には）サポートしていない (*2)
• 参考記事
  • REST APIドキュメント作成ツールはapiary.ioが決定版かもしれない - Qiita
  • 「東京メトロオープンデータ活用コンテスト」②APIの仕様設計を理解し、ドキュメント化する - Qiita
  • http://r7kamura.github.io/2014/02/14/apiary.html

(*1) 新しく API ドキュメントを作成するときに API ドメイン名を決めると

http://docs.[API ドメイン名].apiary.io

という URL でドキュメントにアクセスできるようになる

(*2) ややハック的な方法で実現することは可能

Swagger

http://swagger.io/

• ドキュメント記述方法
  • コード内に API の概要をアノテーションっぽく記述することで、コードベースから自動生成してくれる
• 特徴
  • 作成したドキュメント上に form があり、そこから API コールを試すことができる
  • Swagger のツール群に Swagger Editor というのがあって、これはコードの中でなく YAML 形式でドキュメントが書けるらしいんだけど、Swagger 本体との関連が不明
    • むしろこっちの方がいいんじゃないか
  • python と組み合わせて使えるのはこれかな
    • GitHub - marcgibbons/django-rest-swagger: Swagger Documentation Generator for Django REST Framework: deprecated （Django REST Framework と組み合わせる？）
• 参考記事
  • アノテーションからドキュメントを作れるswaggerの使い方 - gong023の日記

---（追記）---
コード内にアノテーションを書いてドキュメントを生成するのは Swagger の機能の1つで、json または YAML 形式でドキュメントを記述することもできそう。

http://qiita.com/magaya0403/items/0419d84d8df7784ac465

---（追記ここまで）---

I/O Docs

https://github.com/mashery/iodocs

• ドキュメント記述方法
  • JSON
• 特徴
  • node.js で動く
  • （Swagger と同様）作成したドキュメント上に form があり、そこから API コールを試すことができる
• Pros
  • ドキュメントを GitHub で管理するにはシンプルでいいかも (JSON ファイルとコマンドで完結するので)
• Cons
  • JSON ファイル名と置き場が固定されている？（未確認）
    • public/data ディレクトリの下に置くらしい
• 参考記事
  • iodocsで便利なREST APIドキュメントを作成する - Qiita

aglio + api-mock

https://github.com/danielgtaylor/aglio
https://github.com/localmed/api-mock

注）aglio と api-mock はそれぞれ独立したツールです

• ドキュメント記述方法
• 特徴
  • aglio は API Blueprint から HTML 形式のドキュメントを作成するツール
    • npm でインストールして $ aglio -i input.md -o output.html などとする
  • api-mock は API Blueprint から apiary.io が備えているのと同じようなモックサーバを作成するツール
    • こちらも npm でインストール、$ api-mock input.md などとする
• Pros
  • .md ファイルから HTML を生成するだけなので、コードの管理という点では一番シンプルなのでは
  • ファイル名や置き場は自由
• Cons
  • 複数ファイルから HTML 生成はできる？
• 参考記事
  • APIドキュメントを生成するためのMarkdown拡張API BluePrintとその周辺のライブラリ - Qiita

---（追記）---
試してみました。

---（追記ここまで）---

（番外編）Postman

https://www.getpostman.com/

• これはドキュメント作成というより、任意の API リクエストを簡単に試すことができるツールという位置付け？
  • この記事には "API のための Google Docs" って書いてるけど...
    • 迅速安全なAPI開発のためのプラットホームPostmanがシードで$1Mを調達…登録ユーザ数150万に | TechCrunch Japan
• 参考記事
  • Postman - Google Chromeを使ったWeb APIテストクライアント // MOONGIFT Archived

総括

記述方法で言うと Markdown とほぼ同じフォーマットで書ける API Blueprint が魅力的だけど、それなりに学習コストは高そう。 （Markdown を元にしているといっても覚えることは多い）

Apiary.io は日本語での記事が一番見つかったりそれなりに評価もされているという印象なんだけど
意外と自分のニーズとは合ってないんじゃないだろうか。

これは、GitHub と連携できるというのはあくまでおまけであって
基本は web サービス上のエディタで記述し、プレビューですぐに結果を確認しながらドキュメント開発を行うという使い方をしたい人向けだと思う。
私のようにせっかく Markdown っぽく書けるならローカルの vim で書いて必要なときだけ CLI でドキュメントにして確認したい、というなら aglio + api-mock の方がいいと思う。
ただ、こっち使うとなると最終的な成果物をチームで共有するにはどうすればいいんだろうか。