こんな感じ
はじめに
この記事で紹介してる手順は下記の参考サイトと全く同じです。
Swagger 定義ファイルから そこそこいい感じの静的 REST API ドキュメント作成する - Witch on the Other Shore
最近じゃSwaggerとかでAPI定義書いてSwagger UIをどっかにホスティングして配布するみたいな感じの開発も普通になってきたけど、いまだに静的なファイルでAPIドキュメントが必要というケースも結構あると思う。
一応 swagger-codegen でhtmlを出力することもできるんだけど控えめに言って見た目がダサいため、今まではSwagger UIの画面をブラウザで開きPDFで出力するみたいな方法でわりと無理やりドキュメントを生成してた。(めんどくさいので当然メンテナンスしなくなる)
わざわざ自分でツール作るのもめんどくさくて、何かいい方法ないかなーと思って調べたら最初に書いてある記事を発見して、それがわりといい感じだったので紹介してみる。
手順
最初に紹介した記事とおんなじことやってるだけ。
各ツールのビルド方法とか元記事には載ってないところを補足として少し追記。
使うツールとか
-
swagger2markup-cli
- Swagger -> AsciiDocの変換
-
asciidoctor
- AsciiDoc -> HTMLの変換
やってみよう
1. swagger2markup-cliのビルドする
$ git clone https://github.com/Swagger2Markup/swagger2markup-cli.git
$ cd swagger2markup-cli
$ gradle assemble
{PROJECT_ROOT}/build/libsにswagger2markup-cli-{VERSION}.jarが生成されてればOK
2. asciidoctorをインストール
$ gem install --no-doc --no-ri asciidoctor
3. Swagger -> AsciiDoc変換
まずはswagger定義ファイルをAsciiDoc形式に変換する。
使うのは swagger2markup-cli
$ java -jar {swagger2markup-cli_ROOT}/build/swagger2markup-cli-{VERSION}.jar convert -i {SWAGGER_FILE_PATH} -f {OUTPUT_FILE_PATH}
ex) java -jar /usr/local/lib/swagger2markup-cli-1.3.2.jar convert -i swagger.yaml -f swagger
# カレントディレクトリに `swagger.adoc` が生成される
4. AsciiDoc -> HTML変換
最後にasciidoctorを使ってAsciiDoc形式のファイルをHTMLに変換する
$ asciidoctor -a toc=left {ASCII_DOC_FILE_PATH}
ex) asciidoctor -a toc=left swagger.adoc
# カレンドディレクトリに `swagger.html` が生成される
以上。
すごい簡単！！
Dockerイメージ作った
簡単ではあるものの、生成するたびに Swagger -> AsciiDoc -> HTMLとステップ踏むのが面倒だったり、ツールのビルドにGradleやらRubyやらが必要だったりとちょっとめんどくさかったのでドキュメント生成をラップしたDockerイメージ作った。
ryutah/swgger-document - Docker Hub
リポジトリのドキュメントにも書いてあるけどこんな感じでつかう。
$ docker run \
-v {SWAGGER_FILE_DIRECTRY}:{MOUNT_PATH} \
ryutah/swagger-document {SWAGGER_FILE_PATH} {OUTPUT_FILE_PATH}
例) カレントディレクトリの sample.yaml を sample.html としてドキュメント生成
$ docker run \
-v $(pwd):/work \
ryutah/swagger-document /work/sample.yaml /work/sample.html
1つのHTMLとして出力できるから配布も簡単。
ドキュメント出力したいときとかCIに組み込みたいときなんかに使えるんじゃないかな。