こんにちは！インフラアーキテクトの私です。日々、ネットワークの海を渡るパケットや、APIという名の小さな窓口たちを見つめて暮らしています。
さて、皆さんはWebアプリやスマホアプリを作る際、他のシステムとデータをやり取りする「API」の設計や利用に頭を悩ませたことはありませんか？
「URLの設計はどうしよう？」「リクエストのパラメータが変わったら、クライアント側のプログラムも全部書き直さなきゃいけないの……？」そんな泥臭い苦労、よく分かります。
今回は、そんなAPI開発の苦痛を魔法のように消し去り、さらに「型安全性」という最強の盾を手に入れるための秘密兵器、「OpenAPI Generator」について、身近な例えを交えながら優しく紐解いていきたいと思います。
一歩ずつ理解していきましょう！
—
1. 郵便配達員と「注文書フォーマット」の物語
突然ですが、あなたが大きなおもちゃ屋さんの店長さんだと想像してみてください。
毎日、日本全国からお客さんが「このおもちゃが欲しい！」と注文の手紙を送ってきます。
もし、お客さんごとに手紙の書き方がバラバラだったらどうでしょう？
ある人は縦書き、ある人は暗号、ある人は重要な「おもちゃの名前」を書き忘れる……。これではお店のスタッフは注文を処理するだけでヘトヘトになってしまいますよね。
そこであなたは「我が店の注文は、必ずこの専用の注文書フォーマット（設計図）に記入してください！」というルールを作りました。これが、APIの世界における OAS（OpenAPI Specification） です。YAMLやJSONという形式で書かれた、いわば「APIの設計図」になります。
手作業で作る苦労と、自動化のロマン
この設計図があれば、スタッフ（サーバー）も、お客さん（クライアントアプリ）も、みんな同じルールで動けます。
しかし、ここで一つ問題が。
設計図が変わるたびに、お客さん側の注文アプリのプログラムを人間が手作業で書き直していたら、どうでしょう？ ミスも起きるし、何より面倒くさいですよね。
ここで登場するのが、今回の主役である OpenAPI Generator です。
これは、「この設計図（OAS）を渡せば、自動で完璧な注文アプリの部品（SDK）や、お店側の受け付けカウンター（サーバーのスタブコード）を組み立ててくれる全自動ロボット」なんです！
—
2. OpenAPI Generatorとは何か？
OpenAPI Generatorは、YAMLやJSONで書かれたAPIの設計図（OAS）を読み込み、Python、TypeScript、Java、Goなど、あらゆるプログラミング言語のコードを一瞬で生成してくれる強力なツールです。
例えば、バックエンドのエンジニアがAPIの設計図（openapi.yaml）を少し書き換えたとします。
従来なら「おい、APIの仕様が変わったから、フロントエンド側のコードも手動で直してくれよ！」とチャットを飛ばす必要がありました。しかし、OpenAPI Generatorを使えば、その手間が一切なくなります。
なぜ「型安全性」がそんなに大事なのか？
インフラやプログラミングの世界でよく耳にする「型安全性」という言葉。難しく聞こえますが、要するに「間違った荷物をうっかり送ろうとしたら、出発する前に空港のX線検査でガッチリ止められる仕組み」のことです。
例えば、年齢を送るべき場所に、うっかり「こんにちわ」という文字（文字列）を入れてしまったとします。型安全な環境であれば、プログラムを動かす前の「コンパイル」や「ビルド」という準備段階で、「おいおい、ここは数字しか入らない箱だぞ！」と優しく、かつ厳しく教えてくれます。
OpenAPI Generatorを使うと、APIの設計図からこの「型」がビシッと定義されたコードが自動生成されるため、人為的なミス（タイポやデータの勘違い）を未然に防ぐことができるのです。
—
3. 実践！OpenAPI Generatorを動かしてみよう
百聞は一見に如かず。実際にOpenAPI Generatorを動かして、設計図からコードを生成してみましょう。今回はNode.js環境（npxコマンド）を手軽に使って、TypeScriptのクライアントSDKを生成する流れを見ていきます。
まずは、APIの設計図となる openapi.yaml を用意します。
openapi: 3.0.0
info:
title: ほのぼの書店 API
version: 1.0.0
paths:
/books:
get:
summary: 本の一覧を取得する
responses:
'200':
description: 成功時のレスポンス
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Book'
components:
schemas:
Book:
type: object
required:
- id
- title
properties:
id:
type: integer
description: 本の識別番号
title:
type: string
description: 本のタイトルこの設計図には、「/books という場所にGETリクエストを送ると、ID（数字）とタイトル（文字）を持った本のリストがかえってくるよ」という約束事が書かれています。
生成コマンドを実行する
それでは、この設計図をもとに、TypeScriptのクライアントコードを自動生成してみましょう。ターミナル（端末）を開いて、以下のコマンドをペタッと貼り付けて実行します。
# npxを使って、OpenAPI Generatorをインストールせずに直接実行します
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o ./generated-client-i openapi.yaml: 読み込ませる設計図のファイル名を指定しています。-g typescript-axios: 生成する言語とHTTPクライアントの種類（今回はTypeScript向けのAxiosベース）を指定しています。-o ./generated-client: 生成されたコードを保存するフォルダの場所を指定しています。
たったこれだけで、./generated-client フォルダの中に、安全にAPIと通信するための立派なプログラムが一式、自動で生成されます！
—
4. CI/CDパイプラインへの組み込みで「完全自動化」を目指す
さて、手元でコード生成ができるようになったのは素晴らしいですが、実務の現場ではこれを人間の手で毎回実行するのはお勧めしません。「あ、設計図を変えたのに、コードの生成を忘れてた！」といううっかりミスが必ず起きるからです。
そこで、GitHub Actionsなどの CI/CDパイプライン（自動化の仕組み）に組み込んでしまいましょう。
GitHub Actionsの設定例
以下の設定ファイルを .github/workflows/generate-api.yml としてリポジトリに配置しておくと、設計図（openapi.yaml）が更新されるたびに、自動でコードが再生成されるようになります。
name: 自動APIクライアント生成
# mainブランチの設計図が変更されたときに自動で動き出します
on:
push:
branches:
- main
paths:
- 'openapi.yaml'
jobs:
generate:
runs-on: ubuntu-latest
steps:
# 1. リポジトリのコードを手元に持ってくる
- name: リポジトリのチェックアウト
uses: actions/checkout@v4
# 2. Node.jsの環境を準備する
- name: Node.jsのセットアップ
uses: actions/setup-node@v4
with:
node-version: '20'
# 3. OpenAPI Generatorを使ってコードを自動生成する
- name: クライアントSDKの生成
run: |
npx @openapitools/openapi-generator-cli generate \
-i openapi.yaml \
-g typescript-axios \
-o ./src/generated
# 4. 自動生成された変更を自動的にコミットする（お好みで！）
- name: 変更をコミットしてプッシュする
uses: stefanzweifel/git-auto-commit-action@v5
with:
commit_message: "chore: API設計図の変更に伴いクライアントSDKを自動更新"このパイプラインを組んでおけば、開発チームの誰もが「設計図を直すだけ」で、最新の型安全なコードの恩恵を自動的に受け取ることができます。人間が面倒な作業をする必要はもうありません！
—
おわりに
今回は、OpenAPI Generatorを使ったAPI設計図からのコード生成と、CI/CDによる型安全性の維持についてお話ししました。
最初は設定ファイルやコマンドが多くて難しく感じるかもしれませんが、「設計図という一つの真実（Single Source of Truth）から、すべてのコードを自動で生み出す」というアプローチは、一度体験するともう手動には戻れなくなるほどの快適さがあります。
日々の開発やインフラ構築のストレスを減らし、もっとクリエイティブで楽しい部分に集中するために、ぜひ皆さんのプロジェクトでも取り入れてみてくださいね。
それでは、また次の技術の海でお会いしましょう！
コメント