Zenn
🐙

OpenAPI Generator で Ruby のクライアントを生成し、Rails アプリで利用する

に公開
Ruby
OpenAPI
OpenAPI Generator
tech

最近、あるサードパーティー製の API を利用する機会がありました。
公式の Ruby 向けクライアントライブラリは提供されておらず、有志による OSS はゼロではありませんでしたがメンテナンスもあまりされておらず、実運用には少し不安が残る内容でした。

一方で、その API の OpenAPI スキーマが公開されていたため、OpenAPI Generator を使ってクライアントライブラリを自分で生成して利用することにしました。

とても簡単に導入でき便利であったので、備忘録も兼ねて紹介します。

構成と準備

Rails プロジェクトのルートに ./gems ディレクトリを作成し、その中に gem 名と同じ名前のディレクトリを配置しました。以下の3つのファイルを用意しています。

gems/
└── my_api_client/
    ├── openapi.yml
    ├── config.yml
    └── generate_client.sh

openapi.yml

API 提供元が公開している OpenAPI スキーマです。今回は YAML 形式のものを使用しました。

config.yml

OpenAPI Generator に渡す設定ファイルです。以下のように記述しています。

gemName: my_api_client
library: faraday
hideGenerationTimestamp: false

generate_client.sh

Docker を使って openapi-generator-cli を実行するためのスクリプトです。

#!/usr/bin/env bash

DOCKER_IMAGE=openapitools/openapi-generator-cli:v7.13.0
DIRNAME=`dirname $0`

echo "Removing old generated files..."
rm -rf $DIRNAME/generated

echo "Generating new client..."
docker run \
  --rm \
  -v "$PWD/$DIRNAME:/local" \
  $DOCKER_IMAGE generate \
    -i /local/openapi.yml \
    -g ruby \
    -c /local/config.yml \
    -o /local/generated

echo "Done."

openapi-generator を開発マシンに直接インストールすることも考えましたが、チームメンバー全員に環境をセットアップして手間を避けるために Docker を使用する選択肢を選んでいます。

生成物は generated/ ディレクトリに出力されます。生成物には ソースコードだけではなく、Markdown 形式のドキュメントも含まれるためとても便利です。

クライアントの生成と組み込み

クライアントは次のコマンドで生成できます。

./gems/my_api_client/generate_client.sh

生成された gem を Rails プロジェクトで使うには、Gemfile に次のように書きます。

gem 'my_api_client', path: './gems/my_api_client/generated'

bundle install を行うと、通常の gem と同じように使用できるようになります。

Docker 開発環境での対応

開発環境は Docker ベースで構築しています。生成された gem をプロジェクトに含めてコミットしているため、bundle install より前にファイルをコピーする必要があります。

COPY Gemfile Gemfile.lock ./
COPY gems/my_api_client/generated ./gems/my_api_client/generated
RUN bundle install

所感

OpenAPI スキーマがある場合は、OpenAPI Generator を用いてクライアントコードを生成するのが比較的確実で手間も少ないと感じました。

既存の OSS クライアントが合わない場合や、型の整合性を保ちたい場合などに有効な方法だと思います。

Discussion