---
title: "OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで"
url: "https://www.issoh.co.jp/tech/details/4098/"
published: 2024-11-08
updated: 2026-09-27
categories: ["Java"]
publisher: "株式会社一創"
---

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

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

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

## まとめ：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をわかりやすく解説](https://www.issoh.co.jp/tech/details/10408/)で扱っています。

## 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プロジェクトに組み込むなら通信基盤を揃えたほうが依存が単純になります。主要なライブラリは次のとおりです。

| library         | HTTPクライアント              | 向いている場面             |
| --------------- | ----------------------- | ------------------- |
| okhttp-gson（既定） | OkHttp＋Gson             | Spring非依存の汎用クライアント  |
| resttemplate    | Spring RestTemplate     | 既存RestTemplate資産の保守 |
| webclient       | Spring WebClient        | 新規Spring・非同期・並列     |
| restclient      | Spring RestClient（6.1+） | 新規・同期呼び出し（Spring6系） |
| native          | Java標準HttpClient        | 依存最小化（Java 11+）     |
| feign           | OpenFeign               | 宣言的インターフェース統一       |

判断はシンプルです。**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とは何か？概要と基本的な役割を理解しよう](https://www.issoh.co.jp/tech/details/3353/)にまとめています。

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

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

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

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

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

| 症状                 | 原因           | 対処                             |
| ------------------ | ------------ | ------------------------------ |
| 起動失敗（ClassVersion） | JDKが古い       | JDK 11以上を用意。一部libraryはJava 17+ |
| 生成結果がチームで食い違う      | CLIバージョン差    | `openapitools.json`で版を固定       |
| generate前に仕様エラー    | YAML記述ミス     | `validate -i`で事前検証             |
| null・必須の扱いがずれる     | nullable指定漏れ | 仕様で`required`・`nullable`を明示    |

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とは何か？概要と基本的な役割を理解しよう](https://www.issoh.co.jp/tech/details/3353/)
- [OpenAPIとは｜Swaggerとの違い・仕様書(YAML/JSON)の書き方とSwagger UIをわかりやすく解説](https://www.issoh.co.jp/tech/details/10408/)
- [REST APIとGraphQLの違いと使い分け｜選定基準と運用コスト](https://www.issoh.co.jp/tech/details/3591/)

---

出典: [OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで](<https://www.issoh.co.jp/tech/details/4098/>)（株式会社一創）