• トップ
  • ブログ一覧
  • Swaggerで作成したAPIドキュメントをPDF化
  • Swaggerで作成したAPIドキュメントをPDF化

    たなゆー(エンジニア)たなゆー(エンジニア)
    2022.07.01

    IT技術

    APIドキュメントをPDF化

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

    ↓前回の記事↓

    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変換ができるかと思います。

    たなゆー(エンジニア)

    たなゆー(エンジニア)

    おすすめ記事