フロントとバックで型がズレて、同じAPIなのにレスポンスの形が微妙に違う、みたいなことが何度かあって、嫌になっていました。

「OpenAPI first」という開発スタイルを半年ほど実践してみました。コードを書く前にOpenAPI仕様（YAML/JSON）を書いて、そこからフロント・バック両方のコードを生成する、というやつです。

結論だけ先に言うと、万能ではないけど、特定の条件下ではかなり効く、という感じです。

OpenAPI firstとは

コードを書く前にOpenAPI仕様（YAML/JSON）を書く。そこからフロント・バック両方のコードを生成する。

# openapi.yaml
paths:
  /articles:
    get:
      operationId: listArticles
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArticlesResponse'

実際に使ったツールチェーン

  • バックエンド（Go）: oapi-codegen（型定義・ハンドラインターフェース生成）
  • フロントエンド（TypeScript）: orval + TanStack Query
  • 別解（Go）: ogen（oapi-codegenより厳密なバリデーション付きコード生成）
  • フロント側バリデーション: zodとの連携（orvalが対応）

良かったこと

1. 型の一貫性

フロントとバックで型がズレない。これが最大の価値でした。同じAPIを叩いているのに型が違う、というのが根本的に消えます。

2. AIとの相性が良い

Claude Codeに「このOpenAPI仕様に従ってエンドポイント実装して」と言えば、かなり正確なコードが出ます。仕様が先にあると、AIのアウトプットのブレが減る気がします。

3. ドキュメントが常に最新

Swagger UIやRedocで自動生成されるドキュメントは嘘をつかない。

ハマったところ

1. 初期学習コスト

OpenAPI仕様自体が複雑。特にoneOf、anyOfあたりは挙動がツールによって異なる。

2. 柔軟性の低下

「ちょっとだけ仕様変えたい」が重い。YAMLを変更→生成→両方の実装修正、のサイクルが発生。プロトタイプ段階でこれやると、気づいたら仕様書直してるだけで1日終わる、みたいなことがありました。

3. 生成コードの品質差

ツールによって生成されるコードの質が全然違う。orvalは優秀だが、他はイマイチなものも多い。

向いている/向いていない

半年やってみて、自分の判断基準はこうなりました。

向いているケース

  • チーム開発（2人以上）
  • フロント・バックが別チーム
  • 長期運用が前提

向いていないケース

  • 個人開発で高速にイテレーションしたい
  • プロトタイプ段階
  • GraphQL使うなら最初からGraphQL

おわり

OpenAPI firstは銀の弾丸ではないです。ただ、「仕様書とコードの乖離」という古典的問題に対しては、自分が知っている範囲では一番マシな答えでした。

今なら、APIの形が固まってきた段階から導入するのが良さそうです。最初から全部OpenAPIに載せるより、荒いプロトタイプを先に動かして、そのあと仕様書に起こす順番が、自分のペースには合ってました。