OpenAPIを導入し、安心・安全な開発環境を獲得しました

ユニラボ・アイミツチームで開発を担当しているtk2022と申します。アイミツチームでは、10年続いたサービスのフルリプレイスに取り組み、つい先日そのリリースが完了しました。本記事では、リプレイスの一環としてOpenAPIを導入したその経緯や導入により安心・安全な開発環境を獲得したお話を書きます。

リプレイスプロジェクト全体のお話については、同じくアイミツ開発チームエンジニアのdelikuさんが記事を書いておりますのでそちらもぜひご一読ください。

OpenAPI導入の背景

ユニラボが提供しているアイミツというサービスでは、お客様がログイン後にご利用いただけるマイページと社内向け管理画面において、RESTfullなAPIを非同期呼び出しする構成となっております。
リプレイスプロジェクトの初期段階では、Notionを利用してAPI仕様を記述していたのですが、属人化をできる限り排除したフォーマットやフロントエンドからのAPI呼び出しを型安全としたい動機もありOpenAPIの導入に至りました。

使用ツール・構成

OpenAPIの導入のため、以下のツールを使用しました。

openapi-generator-cli
各API仕様を記述するYAMLファイルはメンテナンス性を考慮し、ファイル分割して記述しています。分割したYAMLファイルを1つに統合するためopenapi-generator-cliを利用しています。また、フロントエンドからのAPI呼び出しもOpenAPIの記述内容に沿ったものにするため、typescript-axiosオプションを使用し、typescriptによるAPIクライアントも生成するようにしています。
typescript axiosとYAMLファイルの統合は以下のコマンドにて実行しています。

# typescript axiosの生成
docker-compose run openapi-generator \
    generate -g typescript-axios \
        --api-package=api \
        --model-package=model \
        --additional-properties=withSeparateModelsAndApi=true \
        -i local/src/openapi.yaml \
        -o local/dst

# 分割した記述したopenapi YAMLファイルの統合
docker-compose run openapi-generator \
    generate -g openapi-yaml \
    -i local/src/openapi.yaml \
    -o local/dst

chokidar
YAMLファイル変更後、openapi-generator-cliの再実行を自動化するために導入しています。
以下のようにpackage.jsonを記述し、指定ディレクトリ以下に変更が発生した場合、openapi-generator-cliを実行するスクリプトを呼び出す構成にしています。

"scripts": {
  "watch": "chokidar \"src\" --command \"npm run generate\"",
  "generate": "sh generate.sh"
}

Swagger UI
API仕様の閲覧用に導入しています。以下のコマンドでSwagger UIが立ち上がるようにしました。

$ docker-compose up swagger-ui

GitHub Actions
GitHub Actionsを使用し、プルリクエスト時にopenapi-generator-cliによるOpenAPIのビルドを自動化しています。合わせて、ビルドに失敗した場合、ブランチマージを不可能とするよう設定もしています。これにより、OpenAPIのビルドが通らないブランチがdevelopブランチにマージされることを防止しています。

良かった点

OpenAPIを導入して良かった点は以下の通りです。

API呼び出しが安全となる
フロントエンドからのAPI呼び出しは、OpenAPIをもとに自動生成したtypescript axios経由で行っています。パラメーターの誤りや誤ったエンドポイントへのアクセスはフロントエンドビルド時点で機械的にチェックされるため、実行時エラーが抑制され安全な開発ができるようになりました。そのようにある種のエラーはビルド時点で検出してくれるおかげもあり、安心して開発を進めることができるようにもなりました。

コミュニケーションの円滑化
API仕様をOpenAPIで記述することにより、フロントエンドとバックエンドのI/Fが明確になりました。APIの仕様認識を合わせる際に明確なI/F定義が軸となりエンジニア間でのコミュニケーションが円滑となりました。

明確なAPI仕様書が存在しない状況でのフロントエンド開発は、APIレスポンスが不明確であり、危険で不安な開発体験になると感じますが、OpenAPIによるAPI仕様とtypescriptによるAPIクライアントにより安全で安心なフロントエンド開発を体験できています。特に、実行前のビルド時点で型違反のエラーを発見できることは開発体験の向上に大きく寄与したと感じています。

改善点

OpenAPI導入により良い体験を得つつも以下の改善点を感じております。

YAMLファイル変更時、フロントエンドのビルドに失敗する
リプレイスのフロントエンドではLaravel Mixを使用した、自動ビルドを実行しています。OpenAPI YAMLファイル変更に伴うOpenAPI再ビルド後、typescript APIクライアントのインポートに関連するビルドエラーが発生してしまうことがあります。そうなるとビルドの再実行が必要となり、初期ビルド待ちが発生してしまっています。

仕様と実装の乖離
一部APIにOpenAPIの記述内容とAPIのレスポンスに乖離が発生しており、実行時にエラーとなることがありました。

最後に

以上、OpenAPIを導入して安心・安全な開発環境を獲得したお話でした。
10年運用したサービスのリプレイス目的として、「技術負債の蓄積によりお客様に対して高速で価値を提供できなくなった状況から脱却し、高速で価値を提供する」があり、OpenAPI導入の結果として実現した安全・安心な開発がその一助となっていることを日々実感しています。