APIドキュメントをPDF化

以前Swaggerを使ってAPIのドキュメントを作成する方法を紹介しました。

↓前回の記事↓

2022.04.05SwaggerでAPIドキュメントを作成するSwaggerとは？SwaggerとはAPIのドキュメントを作成するためのツールです。公式説明によると「OpenAPI...

今回はそのドキュメントをPDFに変換する方法について紹介していきます。

PDF化する手順

Swaggerファイルを直接PDFファイルには変換できないので、Swagger → AsciiDoc → PDF という手順で変換していきます。

前提条件として homebrew, ruby, gem がインストールされていないといけません。

筆者の環境は以下の通りです。

1$ brew -v
2Homebrew 3.4.4
3
4$ ruby -v
5ruby 2.6.9
6
7$ gem -v
83.0.3.1

SwaggerファイルをAsciiDocへ変換

SwaggerファイルをAsciidocへと変換する手順を紹介していきます。

Asciidoc への変換はswagger2markup-cliを使って行います。以下のコマンドでswagger2markup-cliをインストールします。

1$ brew install swagger2markup-cli

下記のコマンドでswaggerのファイルをAsciidocへ変換します。

1$ swagger2markup convert -i <swaggerファイル名> -d ./

保存先はコマンドで指定できます。上記のコマンドではルートディレクトリに保存するようにしています。

これでAsciidocファイルがいくつか生成されているので、次はこれをPDFファイルに変換していきます。

AsciiDocをPDFへ変換

AsciiDocをPDFへと変換する方法を紹介していきます。

まずは変換するために使用するasciidoctor-pdfをインストールします。

1$ gem install asciidoctor-pdf

インストールが完了したら、下記のコマンドでpdfに変換していきます。

1$ asciidoctor-pdf -a scripts=cjk -a pdf-theme=default-with-fallback-font <asciidocファイル名>

これでPDFファイルが生成されています。

使用するツールによっては日本語の変換がされない場合もあるようですが、この方法であれば特に気にすることなく日本語でのPDF変換ができるかと思います。