OpenAPI Specification の JSON から PDF を生成する

はじめに

OpenAPI Specification の JSON から、API の PDF ドキュメントを生成したい。

openapi-generator で直接 PDF を出力することはできないけど、AsciiDoc を挟むことで、最終的に PDF ドキュメントを生成できそうだったので試してみた。

OpenAPI Generator をインストール

Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.1.0/openapi-generator-cli-5.1.0.jar

OpenAPI Specification の JSON から AsciiDoc ファイルを生成

openapi-generator から直で AsciiDoc を出力できるようになっていた。

java -jar openapi-generator-cli.jar generate -i openapi.json -g asciidoc -o .\asciidoc

Ruby Installer で Ruby をインストール

AsciiDoc を PDF に変換するツール asciidoctor-pdf は Ruby 製なので、まずは Ruby をインストール必要がある。

rubyinstaller.org

asciidoctor-pdf をインストール

gem install asciidoctor-pdf

TTF ファイルを用意

デフォルトだと PDF の日本語が文字化けしたので、お好みの日本語フォントをダウンロードして使う。

jikasei.me

スタイルファイルを作成

asciidoctor-pdf が用意した日本語フォントを使えるようにするために、デフォルトのスタイルファイルを修正する。

github.com

font:
  catalog:
    GenShinGothic:
      normal: GenShinGothic-Light.ttf
      italic: GenShinGothic-Light.ttf
      bold: GenShinGothic-Medium.ttf
      bold_italic: GenShinGothic-Medium.ttf
base:
  font_family: GenShinGothic
literal:
  font_family: GenShinGothic

PDF 作成

日本語フォントが置かれたフォルダと、修正したスタイルファイルを指定して、asciidoctor-pdf を実行。

asciidoctor-pdf index.adoc -a pdf-style=my-theme.yml -a pdf-fontsdir=fonts -o index.pdf

おわりに

openapi-generatorr から直で PDF まで出せたら最高だけど、さすがにそれは望み薄か。CLI のツールで欲しい。