Swagger 定義ファイルから そこそこいい感じの静的 REST API ドキュメント作成する
REST API のドキュメンテーションはサービス開発における課題として認知されており、解決に向け近年さまざまな試みが行われています。OPEN API および Swagger はその有力な動きの1つです。
長いものには巻かれろ (?) ということで、今回は Swagger 定義ファイルをベースとした REST API ドキュメントの生成方法をまとめます。
結論
swagger2markup-cli と asciidoctor を組み合わせて HTML ファイルを生成するのがよさそうです。
課題の共有
Swggger 定義ファイルからドキュメントを生成する手順はいくつか存在します。
- swagger-ui を利用する
- swagger-codegen で HTML を出力する
swagger-ui はリッチで美しいドキュメントを提供してくれます。しかしインタラクティブな API ドキュメントが必要ない場合、ドキュメント公開のためだけに Node アプリケーションの動作環境を維持しておくことはやや気が重く、できれば静的ファイルとして配置しておきたいところです。
そこで、swagger-codegen の利用が検討できます。
swagger-codegen は、Swagger 定義ファイルからサーバーサイド / クライアントのコードを出力するためのものですが、HTML 形式のドキュメントも出力できたりします。
swagger-codegen generate -i sample.yaml -l html -o output/
しかしながら、インターネットの歴史と伝統のかほりがほのかに醸し出される成果物となっており、このままでは公開しがたい感が否めません。
swagger-codegen で HTML を出力する場合、テンプレートを指定できます。選択肢としては、多少モダンな htmlDocs2 を指定するか、テーマを作成するかです。
今回は swagger-codegen による HTML出力以外のカジュアルな選択肢が必要な状況であるとして、話を進めます*1。
手順
そこそこいい感じの静的 API ドキュメント生成の手順は以下のとおりです。
- Swagger 定義ファイルから Asciidoc を生成する
- Asciidoc から HTML ファイルを生成する
カスタマイズなしで以下のような API ドキュメントが生成できます。
そこそこ良い感じだ。
Swagger to Asciidoc
まずは Swagger 定義ファイルを Asciidoc に変換します。
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 を利用します。
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 定義ファイルの構造を学ぶにあたり、次の記事が非常にわかりやすいです。
ごく単純でフラットな記述から、Swgger の機能を利用して重複部分を徐々に省いていくという構成になっていて、公式ドキュメントではまったく把握出来ない全体像を見事に解説しています。
- 作者: 水野貴明
- 出版社/メーカー: オライリージャパン
- 発売日: 2014/11/21
- メディア: 大型本
- この商品を含むブログ (7件) を見る