OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで

OpenAPI Generatorは、OpenAPI（Swagger）仕様のYAML/JSONから、Javaのクライアント・サーバーコードを自動生成するツールです。手書きの通信コードを減らし、仕様と実装のズレを防げます。

ここではJavaでの利用に絞り、openapi-generator-cliの導入 → generateコマンドの実行 → javaジェネレーターとHTTPライブラリ（RestTemplate/WebClient/RestClient）の選択まで、実際のコマンドとオプションで解説します。ツールの概要や「とは」の整理はOpenAPI Generatorとは何か？概要と基本的な役割を理解しようを参照してください。

まとめ：JavaでOpenAPI Generatorを使う要点

• Javaのクライアントは -g java、Spring Bootのサーバースタブ（コントローラ雛形）は -g spring を使い分ける。
• CLIの導入はnpm版が扱いやすく、Java（JDK 11以上）が必要。Javaを入れたくない場合はDocker版が確実。
• 生成の実体は generate -i 仕様 -g ジェネレーター -o 出力先 の3引数。細かい制御は --additional-properties で渡す。
• javaジェネレーターのHTTPライブラリ既定は okhttp-gson。Springで統一したいなら新規は webclient または restclient を選び、メンテナンスモードの resttemplate は既存踏襲時に限る。
• 生成コードは手編集せず、継承クラスと .openapi-generator-ignore で保護する。バージョンは openapitools.json で固定する。

OpenAPI GeneratorでJavaコードを生成する最短手順

用意するのはOpenAPI仕様ファイル（例 openapi.yaml）だけです。Javaクライアントを出力する最小コマンドは次の形です。

openapi-generator-cli generate \
  -i openapi.yaml \
  -g java \
  -o ./client

-i が入力仕様、-g がジェネレーター名、-o が出力先ディレクトリです。-g java はAPIを呼び出すクライアントコード（モデル＋APIクラス）を生成します。逆にAPIを提供するサーバー側の雛形が欲しい場合はSpring Boot向けの -g spring を指定し、生成されたインターフェースを自分のコントローラで実装します。

仕様ファイルのYAML/JSONの書き方そのものはOpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説で扱っています。

openapi-generator-cliの導入方法（npm・Docker・Homebrew・JAR）

CLIの本体はJava製のため、いずれの方法でもJavaランタイム（JDK 11以上）を前提とします。Dockerだけは例外で、Javaを内包します。

npm版（openapitools.jsonでバージョン固定）

npm install @openapitools/openapi-generator-cli -g

npm版はJava製本体をラップするNodeパッケージです。初回実行時に安定版のJARをダウンロードし、使用バージョンをプロジェクト直下の openapitools.json に記録します。このファイルをコミットしておくと、チーム全員が同じ生成結果を再現できます。

Docker版（Javaを入れずに動かす）

docker run --rm -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml -g java -o /local/client

ローカルにJavaを入れられない、あるいはバージョンを固定したいCI環境ではDocker版が確実です。-v ${PWD}:/local でカレントをコンテナへマウントし、パスはコンテナ内の /local 起点で指定します。

Homebrew版・JAR直接実行

macOSなら brew install openapi-generator でも導入できます。CIで単一ファイルを固定したい場合は、Maven Central（org.openapitools:openapi-generator-cli）からJARを取得し java -jar openapi-generator-cli.jar generate ... で実行します。本稿執筆時点の安定版は7系（7.23.0）ですが、最新版は公式リリースで確認してください。

generateコマンドと主要オプションの使い方

日常的に使うサブコマンドとオプションは限られます。まず利用可能なジェネレーター名の確認と、仕様の妥当性チェックを覚えておくと迷いません。

openapi-generator-cli list          # ジェネレーター一覧
openapi-generator-cli validate -i openapi.yaml   # 仕様の検証
openapi-generator-cli config-help -g java        # javaの設定項目を確認
openapi-generator-cli help generate              # generateの全オプション

生成の細かな制御は --additional-properties（省略形 -p）にキー=値をカンマ区切りで渡します。Javaでよく使うのはパッケージ名とライブラリの指定です。

openapi-generator-cli generate -i openapi.yaml -g java \
  -o ./client \
  --additional-properties=library=webclient,apiPackage=com.example.api,modelPackage=com.example.model

設定を実行前に確認したいときは --dry-run を付けると、ファイルを書き出さずに生成対象を表示します。

Javaジェネレーターとライブラリの選択基準

Javaクライアント（-g java）は、内部で使うHTTPライブラリを library オプションで切り替えます。既定は okhttp-gson（OkHttp＋Gson）で、Springプロジェクトに組み込むなら通信基盤を揃えたほうが依存が単純になります。主要なライブラリは次のとおりです。

判断はシンプルです。RestTemplateはメンテナンスモードのため、新規採用は避け、既存資産の踏襲時だけに限るのが妥当です。同期主体の新規はRestClient、並列・ストリーミングを扱うならWebClientを選びます。シリアライザは serializationLibrary=jackson または gson で切り替えます。Spring Bootは標準でJacksonを使うため、Springのlibraryを選ぶなら serializationLibrary=jackson に揃えると依存の衝突を避けやすくなります。サーバー生成の -g spring でも、Spring Boot 3系では useSpringBoot3=true でjakartaパッケージのスタブを生成します。

Maven・Gradleプラグインでビルド時に生成する

CLIを手で叩く代わりに、ビルド時にコードを生成するプラグインもあります。仕様変更のたびに生成物が更新され、生成コードをリポジトリに残さない運用にできます。

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.23.0</version>
  <executions><execution><goals><goal>generate</goal></goals>
    <configuration>
      <inputSpec>${project.basedir}/openapi.yaml</inputSpec>
      <generatorName>java</generatorName>
      <library>webclient</library>
    </configuration>
  </execution></executions>
</plugin>

Gradleでは org.openapi.generator プラグインを適用し、openApiGenerate タスクに同じ設定を書きます。プラグイン導入の背景やツール全体像はOpenAPI Generatorとは何か？概要と基本的な役割を理解しようにまとめています。

生成コードのカスタマイズと再生成の保護

生成物は再生成のたびに上書きされます。生成されたクラスを直接書き換えると、次の生成で消えるため保守が破綻します。生成コードは手編集しないを原則に、次の2つで独自ロジックを守ります。

• 継承・委譲で拡張する：生成クラスをそのまま使い、追加処理は別パッケージのサブクラスやラッパーに書く。
• .openapi-generator-ignore で除外する：出力ディレクトリに置くと、指定ファイルを生成対象から外して手書き実装を保持できる（.gitignoreと同じ書式）。

出力の書式そのものを変えたい場合は、--template-dir で独自のMustacheテンプレートを指定します。ただしテンプレートの全面改変はバージョン追従を難しくするため、命名規則やヘッダーなど最小限の差分にとどめるのが実務的です。生成物をリポジトリにコミットするか（レビューしやすい／差分が大きい）、ビルド時生成にするか（クリーンだが再現にツールが必要）は、チームで最初に決めておきます。

Javaで使うときのよくあるトラブルと対処

Docker版を使えばローカルのJavaバージョンに左右されないため、CIでの再現性を優先する場合の第一候補になります。

よくある質問

openapi-generator-cliの最新バージョンはどこで確認できますか？

公式のGitHubリリースとMaven Centralで確認できます。本稿執筆時点の安定版は7系（7.23.0）です。プロジェクトでは openapitools.json に版を固定し、最新へ上げる際は生成差分をテストで確認してから切り替えます。

javaジェネレーターとspringジェネレーターはどう違いますか？

-g java はAPIを呼び出すクライアント（モデル＋APIクラス）を、-g spring はAPIを提供するSpring Bootのサーバースタブ（コントローラ用インターフェース）を生成します。呼び出す側ならjava、実装する側ならspringです。

Javaのバージョンはいくつ必要ですか？

CLI本体の実行にはJDK 11以上が必要です。nativeライブラリはJava 11+、Jackson 3を使う一部ライブラリはJava 17+を要求します。使うlibraryに合わせてJDKを選んでください。

Dockerだけで動かせますか？

可能です。openapitools/openapi-generator-cli イメージはJavaを内包するため、ローカルにJavaを入れずに docker run だけで生成できます。CIでの利用にも向いています。

JavaだけでなくPythonやPHPのコードも生成できますか？

できます。-g python や -g php のようにジェネレーター名を変えるだけで、同じ仕様から各言語のクライアントを生成できます。利用可能な一覧は openapi-generator-cli list で確認します。

関連記事

• OpenAPI Generatorとは何か？概要と基本的な役割を理解しよう
• OpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説
• REST APIとGraphQLの違いと使い分け｜選定基準と運用コスト