🤠

OpenAPIをベースにクライアントコードの自動生成(axios利用)

2025/08/11に公開

はじめに

API開発において、クライアントコードの手動実装は、時間と労力がかかるだけでなく、API仕様の変更に追従する際のヒューマンエラーを引き起こす可能性が高まります。OpenAPI Generator CLIを活用すれば、OpenAPI定義ファイルからTypeScriptのクライアントコードを自動生成でき、これらの課題を解決できます。

他にも色々ライブラリ等ありますが個人的に利用していて使いやすかったです。
本記事では、その具体的な手法と、実践的なクライアント設定について解説します。

ライブラリインストール

openapi-generator-cliのインストール
まず、npmまたはyarnでopenapi-generator-cliをインストールします。

npm install @openapitools/openapi-generator-cli
yarn add @openapitools/openapi-generator-cli

クライアントコードの生成

クライアントコードの自動生成
OpenAPI定義ファイル（openapi.yamlやopenapi.jsonなど）を元に、TypeScriptクライアントを生成します。今回はtypescript-axiosジェネレーターを使用し、./types/typescript-axiosディレクトリに出力します。

openapi-generator-cli generate -g typescript-axios -i ./schema/schema.yaml -o ./types/typescript-axios

以下のように追加してnpm run generate-ts-axiosで生成して利用することも可能です

package.json

"generate-ts-axios": "openapi-generator-cli generate -g typescript-axios -i ./schema/schema.yaml -o ./types/typescript-axios"

このコマンドを実行すると、API定義に基づいて型定義やクライアントクラスが自動生成されます。

設定等のカスタマイズ

実践的なクライアント設定の例
生成されたクライアントはそのまま利用できますが、実アプリケーションでは、認証トークンの自動付与や共通のヘッダー設定など、カスタマイズが必要になることがほとんどです。typescript-axiosはaxiosをベースにしているため、axiosのインターセプターを利用してこれらの処理を共通化できます。

以下に、JWT認証トークンを自動でリクエストヘッダーに付与する設定例を示します。

api.ts

import { UserApi } from "@/types/typescript-axios/api";
import { Configuration } from "@/types/typescript-axios/configuration";
import axios from "axios";

// APIのベースURLを環境変数から取得
const API_URL = process.env.API_URL;

// OpenAPIクライアントの共通設定
const config = new Configuration({
  basePath: API_URL,
});

// Axiosインスタンスの生成と設定
const axiosInstance = axios.create({
  baseURL: API_URL,
  withCredentials: true,
});

// Axiosインターセプターを使って、リクエストヘッダーに認証トークンを自動付与
axiosInstance.interceptors.request.use(
  async (config) => {
    // token取得処理等があれば...
    const token = {処理あれば}
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }

    return config;
  },
  (error) => {
    return Promise.reject(error);
  }
);

// OpenAPI定義のtagsが増えるたびに追加(tags毎にApiクラスが生成されます)
const userApi = new UserApi(config, "", axiosInstance);

// クライアントをエクスポート
export { userApi };

この設定ファイルを作成しておけば、userApi等のインスタンスをインポートするだけで、認証トークンの自動付与を気にすることなくAPIを呼び出せます。API仕様が変更された場合も、openapi-generator-cliでクライアントを再生成し、新しいAPIクラスをこのファイルに追加するだけで対応できます。

まとめ

OpenAPI Generator CLIを導入することで、API定義を**唯一の情報源（Single Source of Truth）**として、型安全かつ保守性の高いクライアントコードを自動生成できます。これにより、開発者はAPIの仕様変更に追従する手間から解放され、ビジネスロジックの実装に集中できるようになります。API開発の効率化と品質向上を目指すなら、ぜひこの手法を検討してみてください。

チーム開発だとOpenAPI定義がうまいことまとめられていなかったり(SwaggerUIでちょろっと叩けたら良いくらいのん管理だったり...)することもありますが、この辺りのスキーマを管理してなんちゃってスキーマ駆動のような開発ができるともちろん管理コストはかかりますが整合性を担保しやすいのでよかったです。

個人開発をよくする自分からすると開発しやすく、かつドキュメントとしても利用できるため結構助かりました。
なんか微妙に使いにくいツールも多かったんですが今回利用しているライブラリは使いやすく、axiosクライアントで生成したものをTanStackQueryで利用してキャッシュ管理もしておりますが結構おすすめです。

はじめに

ライブラリインストール

クライアントコードの生成

設定等のカスタマイズ

まとめ

Discussion