dackdive's blog

新米webエンジニアによる技術ブログ。JavaScript(React), Salesforce, Python など

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

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

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

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

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

求めている機能

  • 統一されたフォーマットで書けること(Markdown, JSON, YAML, etc.)
  • 変更履歴を管理できること
  • チーム開発で使えること
  • コードベースと一緒に管理できること

...などなど。

確認できているツール

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

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

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

Apiary.io

https://apiary.io/

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

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

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

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

Swagger

http://swagger.io/

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

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

---(追記ここまで)---

I/O Docs

https://github.com/mashery/iodocs

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

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 生成はできる?
  • 参考記事

---(追記)---
試してみました。

---(追記ここまで)---

(番外編)Postman

https://www.getpostman.com/

総括

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

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

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