メインコンテンツへスキップ
見出し画像

既存APIにOpenAPIコード生成を後付けする現実解

    OpenAPIのコード生成は、新規プロジェクトなら導入しやすいですが、すでに動いているAPIサーバーに後から取り入れるのは一筋縄ではいきません。全部を生成コードに置き換えるのはリスクが大きすぎます。でも、 「インターフェースだけ生成する」 という割り切りなら、既存コードを活かしながらAPI定義と実装の一致を保てます。


    「API定義と実装がズレる」問題、起きていませんか?

    API開発をしていると、こんな状況に心当たりがあるのではないでしょうか。

    ・OpenAPIの定義ファイルはあるけど、実装と微妙にズレている
    ・APIドキュメントを信じてクライアントを実装したら、実際のレスポンスが違っていた
    ・定義ファイルを更新し忘れて、チーム間で混乱が起きた

    私自身、マイクロサービス間のAPI連携で痛い目に遭ったことがあります。「定義ファイルは正しいはず」と信じてフロントエンド側の開発を進めた結果、結合テストで型の不一致が発覚しました。原因を調べると、バックエンド側で3ヶ月前にレスポンス型を変更していたのに、OpenAPI定義の更新が漏れていたのです。修正自体は簡単でしたが、調査と手戻りで丸一日を失いました。

    新規プロジェクトなら「最初からコード生成で全部作る」という選択ができます。しかし、すでに動いているプロジェクトでは、既存のコントローラーやDTO(Data Transfer Object:データ受け渡し用のクラス)を全部捨てて生成コードに置き換えるわけにはいきません。


    後付け導入の現実的な戦略:「契約だけ生成」する

    画像

    ここで有効なのが、 全部を生成に置き換えるのではなく、インターフェース(契約)だけを生成する というアプローチです。

    具体的にはこうします。

    • コントローラーのインターフェースだけ生成する :
      openapi-generator などのツールで、OpenAPI定義からインターフェースを生成します。そのインターフェースを既存のコントローラーにimplementsさせることで、API定義とコントローラーの引数・戻り値の型が必ず一致する状態を作れます

    • DTOは生成結果を正解にする :
      リクエスト・レスポンスのDTOクラスは生成コードをそのまま使います。手書きのDTOとの二重管理をなくせます

    このアプローチの良いところは、 後からエンドポイントを追加しても不整合が起きない 点です。新しいエンドポイントを定義に追加すれば、インターフェースに自動で反映されます。既存の実装を壊すことなく、型レベルの縛りだけをかけられます。


    生成コードの置き場所を分ける

    後付け導入で見落としがちなのが、 生成コードをどこに置くか という問題です。

    既存のソースコードと同じディレクトリに生成コードを混ぜると、厄介なことが起きます。手書きコードと生成コードの区別がつかなくなり、誤って生成ファイルを手動編集してしまうケースが発生します。次の生成実行で上書きされて、せっかくの編集内容が消えてしまうのです。

    解決策はシンプルです。

    • src/generated/java のように専用ディレクトリを作る :
      生成コードの境界が一目でわかります

    • ビルドツールのソースパスに追加する :
      Gradleなら sourceSets.main.java.srcDirs += 'src/generated/java' のように設定します

    • .gitignore に追加するかどうかをチームで決める :
      生成コードをバージョン管理に含めるか、CI/CDで毎回生成するかはプロジェクト方針によります

    こうすることで、コードレビューでも生成ディレクトリは差分確認だけで済み、レビュー負荷も下がります。


    「外部に嘘をつかない」状態を作る

    この方法で得られる最大のメリットは、 外部に提示しているインターフェース定義が、実装と必ず一致している状態を作れる ことです。

    APIを利用するフロントエンドチームや外部パートナーに対して、「このAPI定義は実装と合っています」と自信を持って言えるようになります。定義と実装の一致を人の注意力ではなく、コンパイラの型チェックで担保できるのは大きな安心感です。

    また、AIを活用した開発ワークフローとの相性も良いです。API仕様の変更をOpenAPI定義に反映し、コード生成を実行すると、インターフェースが変わるためコンパイルエラーが発生します。そのエラー箇所を実装すれば、仕様変更への対応が完了します。「どこを直せばいいか」をコンパイラが教えてくれるので、AI支援ツールとの協働にも向いています。


    導入時のよくあるハマりポイント

    実際に後付け導入すると、いくつかの落とし穴があります。

    • 既存DTOと生成DTOの名前衝突 :
      パッケージを分けるか、既存DTOを段階的に生成DTOへ置き換えることで解消できます

    • 生成コードのカスタマイズが足りない :
      openapi-generator の templateDir オプションでMustacheテンプレートを上書きすれば、生成コードのスタイルをプロジェクトに合わせられます

    • チームメンバーへの周知 :
      「生成ディレクトリのファイルは手で編集しない」というルールを、CIで生成ディレクトリの手動変更を検知するチェックを入れて仕組み化しておくとスムーズです


    段階的に導入する手順

    いきなり全エンドポイントを対象にするのは避けましょう。以下の順番で段階的に進めるのがおすすめです。

    • ステップ1 :影響範囲の小さいエンドポイントを1つ選び、OpenAPI定義を書きます

    • ステップ2 :openapi-generator でインターフェースとDTOを生成し、専用ディレクトリに出力します

    • ステップ3 :既存コントローラーに生成インターフェースをimplementsさせ、コンパイルが通ることを確認します

    • ステップ4 :問題がなければ、AIワークフローにコード生成ステップを組み込みます

    • ステップ5 :チーム内で効果を共有し、対象エンドポイントを順次拡大していきます


    まとめ

    既存プロジェクトにOpenAPIのコード生成を後付けする際のポイントを振り返ります。

    • 全置き換えではなく「契約だけ生成」する :
      インターフェースとDTOだけ生成し、既存実装はそれをimplementsする

    • 生成コードは専用ディレクトリに分離する :
      手書きコードとの混在を防ぎ、管理しやすくする

    • 「嘘をつかない」状態を構造的に作る :
      型チェックでAPI定義と実装の一致を担保する

    • 段階的に導入する :
      1つのエンドポイントから始めて、効果を確認しながら範囲を広げる

    「全部やり直す」必要はありません。インターフェースという契約だけを自動化することで、既存のコードを活かしながら、API定義と実装の乖離を防げます。まずは1つのAPIエンドポイントで試してみてください。


    あなたへのおすすめ