ReDoc - Angular な静的 Webページを生成できる REST API ドキュメンテーションツール

REST API のドキュメンテーションツールにはいまだこれといった決定打がなく、定期的に「API document tool 2017」などのワードでぐぐってはブラウザを閉じ、ぐぐってはブラウザを閉じるという悶々とした日々を過ごしていました。そんなおり、以下の記事で「ReDoc」というツールを知りました。

簡単にさわってみたところ感じがよかったので紹介します。

なお、本稿で「API」と記載する場合 Web Application の RESTful API を指します。

ReDoc

ReDoc は、API ドキュメントのジェネレーターです。

github.com

手元で作成した成果物のスクリーンショットを掲載します。

f:id:iktakahiro:20170609022023p:plain

詳細は LiveDemo をご覧いただくのがよいでしょう。

ReDoc の特長

ReDoc の特長は以下のとおりです。

  • HTML に redoc.min.js と swagger.json を読み込ませるだけというお手軽設計
  • ドキュメントは Angular ベースの HTML + JS な静的ファイルとして出力される

利用方法

README のとおりですが、アプリケーションの JavaScript と API の定義ファイルを読み込むのみです。

<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="http://petstore.swagger.io/v2/swagger.json"></redoc>
    <script src="https://rebilly.github.io/ReDoc/releases/latest/redoc.min.js"></script>
  </body>
</html>

ローカルの swagger.json を読み込む場合は Web サーバー経由でアクセスします。

ReDoc のよさ

ReDoc のよさを語ります。

静的ファイルであることのよさ

現存する API ドキュメンテーションツールにはモック機能や実際のリクエストを発行できる機能が備わっている場合があります。Swagger UI がその代表例です。

リッチな機能を提供するためか、Swagger UI はサーバーサイドアプリケーションとして実装されていますが、 ごく個人的には、API の入出力情報を示す程度の目的を果たすために、アプリケーションサーバーを運用したくないと考えています。

ReDoc による API ドキュメントは静的ファイルとして構成されます。したがって GitHub PagesAWS S3 などを利用して Static Web Site としてドキュメントを公開できます。

デフォルトスタイルのよさ

ReDoc はデフォルトのスタイルが美しく、そのままで公開クオリティ感があります。3ペインスタイルは、しばしば API Docs 界隈(?)でお手本とされる Stripe.com の API ReferenceAuth0 の API Docs を参考にされているのではないかと推察されます。

構成もシンプルで、サービスロゴを入れたりカラムの色を調整するだけでもほどよいオリジナリティを出せる設計だと思います。

OpenAPI (Swagger) Specification を利用できることのよさ

ここ最近その動向がまったくオープンに感じられない Open API Initiative にはかなり色々思うところがありますが、さておき、OpenAPI (旧Swagger) Specification が API ドキュメントの定義ファイルとして一定の存在感を示していることは否定できません。

OpenAPI Specification のつらさもあってか、RAML のように別の “alt-YAML 的な何か” に走る動きや、そもそも JSON や YAML は無理なので、lord/slate のように Markdown で定義を書かせようという試みも見られます*1

しかしながらひとめぐりしてみると、エコシステムは大きいほうがよいということと、フォーマットとして将来変換可能であったほうがよい *2 といった理由により、次善の策として OpenAPI Specification を採用しておくのは悪手ではないように思われます。

ReDoc は OpenAPI Specification をそのまま利用できるので、いままで Swagger を利用していた場合には資産を活かせます。将来 Swagger 方面に合流することになっても問題ありません。

おわりに

API ドキュメンテーションツールは多く存在します。その中で ReDoc は、OpenAPI Specification を利用しつつ品質のよい静的 Webページを生成する*3というバランスのよいポジションに属していると思います。

まずは現存する自社の API Document をリプレースしてみようと考えています。API ドキュメンテーションをめぐるツールやプラクティスについてどこかで意見交換できるとよいですね。

*1:Apiary… うっ…頭が…

*2:Markdown のような書式では仕様がファジーになりやすく JSON や YAML などに相互変換しにくいという問題があります。仕様によりますが

*3:HTML ファイルが generate されるわけではないので、変換といったほうが適切かも知れません