日本語を含む Swagger の PDF 化を Mac でやりたい

はじめに

テントの中から失礼します、CX事業本部のてんとタカハシです！

Swagger は API 仕様をコードで管理できる便利なツールですが、時たま PDF に変換したいことがあります。その際、日本語が混じっていると文字化け問題が発生したりするので、その対処法について記事にします。

環境

環境は下記の通りです。 Ruby と Java がインストールされていることを前提とさせて頂きます。

$ sw_vers
ProductName:	Mac OS X
ProductVersion:	10.14.6
BuildVersion:	18G103

$ rbenv --version
rbenv 1.1.2-40-g62d7798

$ ruby --version
ruby 2.6.6p146 (2020-03-31 revision 67876) [x86_64-darwin18]

$ gem --version
3.0.3

$ java -version
java version "11.0.10" 2021-01-19 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.10+8-LTS-162)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.10+8-LTS-162, mixed mode)

Swagger で作成した API 仕様

これを PDF に変換します。

swagger.yaml

swagger: '2.0'
info:
  version: '1.0.0'
  title: 'サンプル API'
  description: 'これはサンプル API です'
host: 'example.classmethod.jp'
tags:
  - name: 'User'
    description: 'ユーザー情報'
schemes:
  - 'https'
paths:
  /users:
    post:
      tags:
        - 'User'
      summary: 'ユーザーを登録する'
      consumes:
        - 'application/json'
      produces:
        - 'application/json'
      parameters:
        - in: 'body'
          name: 'body'
          description: '登録するユーザーの情報'
          required: true
          schema:
            $ref: '#/definitions/Request'
      responses:
        '200':
          description: 'OK'
          schema:
            $ref: '#/definitions/Response'
definitions:
  Request:
    type: 'object'
    required:
      - 'name'
      - 'age'
    properties:
      name:
        type: 'string'
        description: '名前'
        example: 'てんとタカハシ'
      age:
        type: 'number'
        description: '年齢'
        example: 26
  Response:
    type: 'object'
    required:
      - 'userId'
    properties:
      userId:
        type: 'string'
        description: 'ユーザーID'
        example: '38ec8aaa-fd09-4a9e-bbad-03e87e4765a6'

手順

Swagger→AsciiDoc→PDF の順に変換していきます。AsciiDoc から PDF に変換する際に、日本語フォントを使用します。

Swagger を AsciiDoc に変換する

swagger2markup-cliというツールを使用して、Swagger を AsciiDoc に変換します。下記からjarファイルをダウンロードして、作業用のディレクトリに移動してください。

https://jcenter.bintray.com/io/github/swagger2markup/swagger2markup-cli/1.3.3/

その後、下記のコマンドで Swagger を AsciiDoc に変換します。変換した後は、1つの AsciiDoc にファイルをまとめます。

$ java -jar ./swagger2markup-cli-1.3.3.jar convert -i ./swagger.yaml -d ./adoc
$ cat adoc/overview.adoc adoc/paths.adoc adoc/definitions.adoc > adoc/out.adoc

AsciiDoc を PDF に変換する

AsciiDoc を PDF に変換するためのツールをインストールします。

$ gem install asciidoctor
$ gem install --pre asciidoctor-pdf

日本語フォントをインストールします。

$ gem install asciidoctor-pdf-cjk-kai_gen_gothic
$ asciidoctor-pdf-cjk-kai_gen_gothic-install

gem でインストールしたファイルがどこに置かれているのか確認した後（INSTALLATION DIRECTORY）、KaiGenGothicJP-theme.ymlを作業用ディレクトリにコピーします。

$ gem environment
RubyGems Environment:
  - RUBYGEMS VERSION: 3.0.3
  - RUBY VERSION: 2.6.6 (2020-03-31 patchlevel 146) [x86_64-darwin18]
  - INSTALLATION DIRECTORY: /Users/<UserName>/.anyenv/envs/rbenv/versions/2.6.6/lib/ruby/gems/2.6.0
  ...
  
$ cp /Users/<UserName>/.anyenv/envs/rbenv/versions/2.6.6/lib/ruby/gems/2.6.0/gems/asciidoctor-pdf-cjk-kai_gen_gothic-0.1.1/data/themes/KaiGenGothicJP-theme.yml ./

AsciiDoc を PDF に変換します。

$ asciidoctor-pdf -r asciidoctor-pdf-cjk-kai_gen_gothic ./adoc/out.adoc -a pdf-style=KaiGenGothicJP-theme.yml -o output.pdf

できたもの

最終的にできた PDF はこんな感じになりました。日本語も良い感じに表示できてますね。

参考にさせて頂いた記事

おわりに

今月もなんとか記事を4本書けました。気付けば2021年もう1ヶ月経つのか恐ろしや、、、ということで来月も頑張ります。

今回は以上になります。最後まで読んで頂きありがとうございました！