こんにちは！開発現場で日々、APIのドキュメントと手書きのクライアントコードの乖離に頭を悩ませていませんか？
「バックエンドの仕様変更に合わせて、フロントエンドのTypeScriptの型定義を直して、APIクライアントのラッパー関数も書き換えて……あぁ、またバグが出た！」
そんな泥臭い作業とは、今日でサヨナラしましょう。
今回は、世界中のプロフェッショナルが愛用する「OpenAPI Generator」を使って、Swagger（OpenAPI）定義から、TypeScript（フロントエンド用）とGo（バックエンドのマイクロサービス間通信用）のクライアントコードを完全に自動生成する方法を解説します。
これをマスターすれば、APIの変更は一瞬でコード全体に伝播し、手動でのタイポや型ミスの地獄から完全に解放されますよ。さあ、一緒にスマートな開発の世界へ飛び込みましょう！
—
1. なぜコード自動生成なのか？型安全が生む圧倒的な開発体験
私たちがAPIを呼び出すとき、最も恐ろしいのは「実際にリクエストを送るまでエラーに気づけない」ということです。
例えば、JavaScriptや型のない環境でAPIを叩く場合、プロパティ名を `userId` と書くべきところを `userid` と書いてしまい、本番環境でクラッシュする……なんて事故は後を絶ちません。
自動生成がもたらす3つの果実
1. 完全な型安全性（Type Safety）: API定義（Swagger）が「正（シングル・ソース・オブ・トゥルース）」となります。定義を変えてコードを再生成するだけで、IDEが「ここ修正漏れてるよ！」と赤く教えてくれます。
2. 手書きコードの完全排除: ボイラープレート（お決まりのHTTPクライアント設定やシリアライズ処理）を書く必要は二度とありません。
3. 言語間のシームレスな連携: Goで作った高パフォーマンスなバックエンドAPIを、TypeScriptのフロントエンドや別のGo製マイクロサービスから、まるでローカルの関数を呼ぶかのように安全に呼び出せます。
—
2. 環境構築と `openapi-generator-cli` の導入
それでは早速、手を動かしながら進めましょう。
OpenAPI GeneratorはJavaで書かれていますが、Node.js環境であれば `npm`（または `npx`）経由で手軽に実行できます。今回はプロジェクトごとにバージョンを固定できるローカルインストールをおすすめします。
ステップ1: ツールの導入
プロジェクトのルートディレクトリで、以下のコマンドを実行してください。
開発用依存関係としてCLIをインストール
npm install @openapitools/openapi-generator-cli –save-dev
ステップ2: 魔法のレシピ（設定ファイル）の作成
毎回長ったらしいコマンドを叩くのはエンジニアの美学に反します。プロジェクトのルートに `openapi-config.yaml` という設定ファイルを作りましょう。
`openapi-config.yaml`
OpenAPI Generatorの共通設定ファイル
ここに生成ルールを定義することで、チーム全員が同じ品質のコードを出力できます。
generatorName: typescript-axios # デフォルトはTypeScript用Axiosクライアントを指定
inputSpec: ./api-schema.yaml # 読み込むSwagger定義のパス
output: ./src/generated-api # 出力先ディレクトリ
additionalProperties:
supportsES6: “true”
npmName: “my-api-client”
npmVersion: “1.0.0”
※今回は「TypeScript (Axiosベース)」を例にしますが、Go言語のクライアントを出力したい場合は、後述するコマンドライン引数で自在に切り替えられます。
—
3. 実践！Swagger定義からクライアントを召喚する
準備が整いました。テスト用の小さなSwagger定義（`api-schema.yaml`）を用意したと仮定して、実際にコードを生成してみましょう。
サンプルのSwagger定義 (`api-schema.yaml`)
openapi: 3.0.0
info:
title: 冒険者管理API
version: 1.0.0
paths:
/adventurers:
get:
summary: 冒険者一覧を取得する
responses:
‘200’:
description: 成功
content:
application/json:
schema:
type: array
items:
$ref: ‘#/components/schemas/Adventurer’
components:
schemas:
Adventurer:
type: object
required:
- id
- name
- job
properties:
id:
type: string
format: uuid
name:
type: string
job:
type: string
example: “魔法使い”
コード生成のコマンド実行
それでは、以下のコマンドを叩いてコードを自動生成します。
設定ファイルに従ってTypeScriptクライアントを生成
npx openapi-generator-cli generate -c openapi-config.yaml
たったこれだけで、`./src/generated-api` の中に、Axiosをベースにした完璧なTypeScriptのAPIクライアント一式（型定義、API呼び出し関数など）が生成されます！
—
4. 生成されたSDKを呼び出す（TypeScript & Go）
生成されたコードが、いかに美しく、そして使いやすいかを見てみましょう。
① フロントエンド（TypeScript）での実践例
生成されたモジュールをインポートするだけで、IDEの補完が効きまくる安全なAPIコールが実現します。
import { Configuration, AdventurersApi } from ‘./generated-api’;
// APIクライアントの設定（ベースURLを指定）
const config = new Configuration({
basePath: ‘https://api.example.com’,
});
// APIインスタンスの生成
const adventurersApi = new AdventurersApi(config);
async function fetchAdventurers() {
try {
// 戻り値の型も自動で推論される！
const response = await adventurersApi.adventurersGet();
response.data.forEach((adventurer) => {
// id, name, job の補完が効く。typoの心配はゼロ！
console.log(`${adventurer.name} (${adventurer.job})`);
});
} catch (error) {
console.error(‘API通信に失敗しました:’, error);
}
}
② マイクロサービス間通信（Go）での実践例
ちなみに、Go言語のクライアントが欲しい場合は、コマンドのジェネレーター指定を変えるだけです。
Go言語用のクライアントコードを生成する場合
npx openapi-generator-cli generate \
-i api-schema.yaml \
-g go \
-o ./client-go
生成されたGoのコードも非常にシンプルに使えます：
package main
import (
“context”
“fmt”
“log”
“your-project/client-go”
)
func main() {
// デフォルトの設定でクライアントを初期化
client := swaggermodule.NewAPIClient(client-go.NewConfiguration())
// API呼び出し
adventurers, httpResp, err := client.AdventurersApi.AdventurersGet(context.Background()).Execute()
if err != nil {
log.Fatalf(“エラーが発生しました: %v”, err)
}
defer httpResp.Body.Close()
for _, adv := range adventurers {
fmt.Printf(“冒険者: %s (職種: %s)\n”, adv.Name, adv.Job)
}
}
—
5. 先輩エンジニアからのアドバイス：CI/CDへの組み込み
この自動生成の真価は、「Gitのプレコミットフック」や「GitHub ActionsなどのCI/CDパイプライン」に組み込むことで発揮されます。
バックエンドの開発者がSwagger定義（`api-schema.yaml`）を更新してプルリクエストを投げた際、CI上で自動的にクライアントコードが再生成されるようにしておけば、「APIを変えたのにフロントの更新を忘れた」というヒューマンエラーを機械的に防ぐことができます。
まとめ
- Swagger/OpenAPI定義を絶対の正とする。
- `openapi-generator-cli` を使って、TypeScriptやGoなどのクライアントをワンコマンドで生成する。
- 型安全なコードにより、手動コーディングのミスやバグを根絶する。
これをマスターすれば、API連携にかかっていた無駄なデバッグ時間が劇的に減り、本当に価値のあるビジネスロジックの実装に集中できるようになりますよ。
あなたの開発ライフが、より快適でエキサイティングなものになりますように！