Swagger 定義ファイルから そこそこいい感じの静的 REST API ドキュメント作成する

REST API のドキュメンテーションはサービス開発における課題として認知されており、解決に向け近年さまざまな試みが行われています。OPEN API および Swagger はその有力な動きの1つです。

長いものには巻かれろ (?) ということで、今回は Swagger 定義ファイルをベースとした REST API ドキュメントの生成方法をまとめます。

結論

swagger2markup-cliasciidoctor を組み合わせて HTML ファイルを生成するのがよさそうです。

課題の共有

Swggger 定義ファイルからドキュメントを生成する手順はいくつか存在します。

  • swagger-ui を利用する
  • swagger-codegen で HTML を出力する

swagger-ui はリッチで美しいドキュメントを提供してくれます。しかしインタラクティブな API ドキュメントが必要ない場合、ドキュメント公開のためだけに Node アプリケーションの動作環境を維持しておくことはやや気が重く、できれば静的ファイルとして配置しておきたいところです。

そこで、swagger-codegen の利用が検討できます。

github.com

swagger-codegen は、Swagger 定義ファイルからサーバーサイド / クライアントのコードを出力するためのものですが、HTML 形式のドキュメントも出力できたりします。

swagger-codegen generate -i sample.yaml -l html -o output/

しかしながら、インターネットの歴史と伝統のかほりがほのかに醸し出される成果物となっており、このままでは公開しがたい感が否めません。

f:id:iktakahiro:20161122203315p:plain:w400

swagger-codegen で HTML を出力する場合、テンプレートを指定できます。選択肢としては、多少モダンな htmlDocs2 を指定するか、テーマを作成するかです。

今回は swagger-codegen による HTML出力以外のカジュアルな選択肢が必要な状況であるとして、話を進めます*1

手順

そこそこいい感じの静的 API ドキュメント生成の手順は以下のとおりです。

  1. Swagger 定義ファイルから Asciidoc を生成する
  2. Asciidoc から HTML ファイルを生成する

カスタマイズなしで以下のような API ドキュメントが生成できます。

f:id:iktakahiro:20161122200815p:plain:w600

そこそこ良い感じだ。

Swagger to Asciidoc

まずは Swagger 定義ファイルを Asciidoc に変換します。

github.com

swagger2markup の 実行例は以下のとおりです。

$ java -jar swagger2markup-cli-1.1.0.jar convert -i sample.yaml -f api-doc

実行すると api-doc.adoc が出力されます。

= Simple API


[[_overview]]
== Overview
A simple API to learn how to write OpenAPI Specification


=== Version information
[%hardbreaks]
_Version_ : 1.0.0

Asciidoc to HTML

続いて Asciidoc を HTML に変換します。asciidoctor を利用します。

github.com

asciidoctor の実行例は以下のとおりです。

$ asciidoctor -a toc=left api-doc.adoc

実行すると api-doc.html が出力されます。

-a オプションに toc=left を指定することで サイドバーに Table of Contents が出力されたレイアウトを選択できます。

ここで紹介した一連のビルドプロセスを CI に反映して、Amazon S3 などに Deploy できるようにしておけばよいでしょう。

付録

その他の REST API ドキュメンテーションツール/サービス

Product Description
Apiary 国内で認知度が高いっぽい API ドキュメンテーション + Mock 生成できるクラウドサービス。噛めば噛むほど渋い思いをするらしい (?)。
RAML YAMLっぽいなにか からコードやドキュメントを生成するツール群。RESTful API Modeling Language で RAML とのこと。

一時期は群雄割拠感もあった API ドキュメンテーションツール界隈ですが、ここ2年くらいで淘汰が進んできた印象です。RAML は設計がモダンな感じなので普及して欲しいです*2

Swagger 定義ファイルの学習

最近見つけたのですが Swagger 定義ファイルの構造を学ぶにあたり、次の記事が非常にわかりやすいです。

apihandyman.io

ごく単純でフラットな記述から、Swgger の機能を利用して重複部分を徐々に省いていくという構成になっていて、公式ドキュメントではまったく把握出来ない全体像を見事に解説しています。

Web API: The Good Parts

Web API: The Good Parts

*1:テーマ作成については別の機会で

*2:と言いつつ Swagger に巻かれる勢