「OpenAPI first」という開発スタイルを半年ほど実践してみた。結論、万能ではないが特定の条件下では非常に有効。

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. 型の一貫性

フロントとバックで型がズレない。これが最大の価値。

2. AIとの相性が良い

Claude Codeに「このOpenAPI仕様に従ってエンドポイント実装して」と言えば、かなり正確なコードが出る。

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

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

デメリット

1. 初期学習コスト

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

2. 柔軟性の低下

「ちょっとだけ仕様変えたい」が重い。YAMLを変更→生成→両方の実装修正、のサイクルが発生。

3. 生成コードの品質差

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

向いているケース

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

向いていないケース

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

おわり

OpenAPI firstは銀の弾丸ではない。ただ、「仕様書とコードの乖離」という古典的問題に対する現実解の一つではある。