目次- 🤖 OpenAPIとAIは親和性が高そう
- 💪 OpenAPIコード生成の威力
- 📝 AIが提案してくれた具体的な使い方
- ⚠️ AIが警告してくれた注意点と対策
- 🎯 AIのアドバイスを聞いて感じたメリット
- 🌟 まとめ：AIに教えてもらって良かった！
🤖 OpenAPIとAIは親和性が高そう
最近、開発効率を上げる方法をAIに相談していたら、OpenAPIからのコード生成という手法を教えてもらいました。
確かに、前回記事でも書いたように、OpenAPIは"API仕様の標準化"を実現するための仕様。
これにはルールがあり、機械にも読みやすいはず。
というわけで、今回はAIから教えてもらったOpenAPIコード生成の活用法と、実装時の注意点をまとめて、いろいろ考えてみました。
💪 OpenAPIコード生成の威力
AIの説明によると：
- API仕様書（YAML/JSON）を書くだけで、サーバーコードもクライアントSDKも自動生成
- 型定義も自動で作られるから、型の不整合が起きない
- ドキュメントも仕様書から自動生成されるので常に最新
- PostmanやInsomniaのコレクションまで作れる
なるほど、仕様書を中心に全てが自動化できるということか。
📝 AIが提案してくれた具体的な使い方
まず、以下のようなOpenAPI仕様書を書く
# openapi/api.yml
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths:
/api/v1/users:
get:
summary: ユーザー一覧取得
operationId: getUsers
parameters:
- name: page
in: query
schema:
type: integer
minimum: 1
responses:
'200':
description: 成功
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
そして、コマンドを実行するだけ：
# サーバーコード生成（Rails用）
openapi-generator-cli generate \
-i openapi/api.yml \
-g ruby-rails \
-o generated/server
# クライアントSDK生成（TypeScript用）
openapi-generator-cli generate \
-i openapi/api.yml \
-g typescript-fetch \
-o generated/client
すると、こんなコードが自動で生成されるらしい！
Railsコントローラー：
def get_users
page = params[:page]&.to_i || 1
# バリデーションも自動生成！
if page < 1
render json: { error: 'page must be >= 1' }, status: :bad_request
return
end
# あとは実装するだけ
users = User.page(page)
render json: users
end
TypeScriptクライアント：
// 型安全なAPIクライアント！
async getUsers(page?: number): Promise<UserList> {
const response = await this.api.get('/api/v1/users', {
params: { page }
});
return response.data;
}
これができるなら、確かに開発効率爆上がりですね！
⚠️ AIが警告してくれた注意点と対策
「簡単そうだけど、何か落とし穴ない？」って聞いたら、いくつか教えてくれました。
1. 生成コードがプロジェクトの規約に合わない問題
AI：「デフォルトの生成コードは汎用的なので、プロジェクトの規約に合わないことがあります」
対策：カスタムテンプレートを使う
{{! カスタムテンプレート例 }}
def {{operationId}}
# プロジェクトの規約に合わせた実装
permitted_params = params.permit({{#allParams}}:{{paramName}}{{#hasMore}}, {{/hasMore}}{{/allParams}})
result = {{classname}}Service.call(permitted_params)
render json: result
end
2. 生成コードを直接編集してしまう問題
AI：「生成したコードを直接編集すると、次回生成時に上書きされます」
対策：継承やラッパーで拡張する
# 生成されたコード（触らない）
class GeneratedUsersController < ApplicationController
def get_users
# 自動生成されたコード
end
end
# 拡張用のコントローラー
class Api::V1::UsersController < GeneratedUsersController
def get_users
# カスタムロジックを追加
log_api_access
super
end
end
3. CI/CDでの生成が難しい問題
AI：「環境依存で生成結果が変わることがあります」
対策：Dockerで環境を固定
FROM openapitools/openapi-generator-cli:latest
WORKDIR /app
COPY openapi/api.yml .
RUN openapi-generator-cli generate \
-i api.yml \
-g ruby-rails \
-o /generated
🎯 AIのアドバイスを聞いて感じたメリット
AIと話していて、こんなメリットがありそうだと感じました：
開発効率の向上
- 仕様書を書けば実装の大部分が自動化
- 型の不整合によるバグが減る
- ドキュメント更新の手間がなくなる
チーム開発での利点
- フロントエンドとバックエンドで認識が統一される
- API仕様のレビューに集中できる
- 新メンバーも仕様書を見れば理解しやすい
特に効果的なケース
- マイクロサービス間のAPI連携が多い
- 複数言語でSDKを提供する必要がある
- 外部向けAPIでドキュメントが重要
🌟 まとめ：AIに教えてもらって良かった！
今後、「設計フェーズをいかに正確に行うか」がチームの生産性に大きく関わること予感させる良い調査でした。
また、AIライクな設計、いかにAI生成ブレの少ない仕様書にするか、がこれから求められる力のように感じます。
AIが強調していたポイント：
- 仕様ファーストの開発で品質向上
- 自動化による大幅な工数削減
- 型安全性の確保
確かに導入には若干学習含め負荷がかかりそうだけど、長期的に見れば絶対お得すぎる。
結局はAIは自分の写し鏡。新しく出てきたものと、"自分の知識"を合わせることが活用の種ですね。
数年後は写し鏡ではなく、大きく見せてくれるようになるのかな？