これはこれで手軽にAPIの仕様を確認出来て便利なのですが、受託開発の際の納品物としてお客様に渡すには少し不便です。「納品は紙（PDF）で」と言われる事がまだありますよね？
ブラウザに表示されているものを印刷して渡してしまっても良いかもしれませんが、それだと今ひとつ見栄えが良くないので出来ればもう少しきれいなPDF文書を自動生成したいところです。
そこで調べたところ、次のような事が分かりました。
● swagger2markup-cli を使えばSwaggerが生成するJSONファイルから静的なHTMLやMarkdown、AsciiDoc形式のドキュメントなどを生成する事が出来る。
● asciidoctor-pdf を使えばAsciiDoc形式のドキュメントをPDFファイルに変換する事が出来る。
参考：
goa tips: swagger-ui がサービスできないときのドキュメントどうする問題 - 押してダメならふて寝しろ
asciidocをPDFに変換してみた（asciidoctor-pdf）
今回はこれらを使って
swagger.json → AsciiDoc → PDFという流れでドキュメントを生成する事にします。
まず前提条件として、swagger2markup-cliを使うにはJavaのインストールが必要で、asciidoctor-pdfを使うにはRubyのインストールが必要になります。
Macで開発しているのあれば通常は両方とも既に入っていると思います。Windowsの場合はchocolateyを使えば簡単にインストール出来ると思います。
1. swagger2markup-cliでAsciiDocファイルを生成する
下のURLからjarファイルをダウンロードします。
https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/
ダウンロード後、コマンドラインから下記を実行します。
java -jar ./swagger2markup-cli-1.3.1.jar convert -i [swagger.jsonへのパス] -d ./adoc
[swagger.jsonへのパス]の部分は 「http://localhost:49879/swagger/v1/swagger.json」のようにURLを指定しても良いし、「./swagger.json」のようにあらかじめダウンロードしておいたJSONファイルを指定しても構いません。
エラーが出ずに成功すれば、adocフォルダには overview.adoc, paths.adoc, definitions.adoc, security.adoc の4つのファイルが出来ているはずです。ファイルが分かれていると次のステップで困るので、1ファイル(out.adoc)に結合しておきます。
cat adoc/overview.adoc adoc/paths.adoc adoc/definitions.adoc > adoc/out.adoc
(security.adocの内容は特に必要がなかったので除外しました。)
2. asciidoctor-pdfでPDFファイルを生成する
gemコマンドでasciidoctor-pdfをインストールします。
gem install --pre asciidoctor-pdf
あとは入力と出力を指定して実行するだけです。
asciidoctor-pdf -o pdf/out.pdf adoc/out.adoc
これでpdfフォルダにout.pdfファイルが生成されます。サンプルはこんな感じです。
デフォルトのスタイルが物足りなければ、テーマを自作して色々とカスタマイズ出来るようです。
asciidocをPDFに変換してみた（asciidoctor-pdf）
さて、ここまででWeb APIからPDFドキュメントを生成する事が出来ました。ただ、APIに変更が発生する度にコマンドを打ち込んでPDFを再生成するのはちょっと面倒です。
そこで次回は、今流行りの「Continuous Integration（CI）」なるものを使ってソースコードの変更をプッシュするだけで自動的にPDFドキュメントが更新される、という事にチャレンジしてみたいと思います。
次回： GitLab CIを使ってWebAPIのPDFドキュメント生成を自動化する