--- title: "OpenAPI Generatorとは？使い方・生成されるコード・Maven設定を実行例で解説" url: "https://www.issoh.co.jp/tech/details/3353/" published: 2024-08-20 updated: 2026-10-18 categories: ["API"] publisher: "株式会社一創" --- # OpenAPI Generatorとは？使い方・生成されるコード・Maven設定を実行例で解説 OpenAPI Generatorは、OpenAPI仕様（旧Swagger仕様）で書いたAPI定義から、クライアントSDK・サーバースタブ・APIドキュメントを生成するオープンソースのツールです。2026年10月6日公開の最新版7.26.0では、既定の一覧に165種類のジェネレーターがあります。この記事では、7.26.0で小さなTodo APIの仕様からコードを生成し、出力されるファイル、生成されたコード、仕様の誤りを止める`validate`、Mavenプラグインで詰まりやすい依存関係までを実行結果つきで説明します。 ## まとめ：OpenAPI Generatorの要点 - OpenAPI仕様（YAML/JSON）を入力に、クライアントSDK・サーバースタブ・ドキュメントを生成するApache License 2.0のOSS。2018年にSwagger Codegenからフォークした。 - 最新安定版は7.26.0（2026年10月6日）。7.xではマイナー版がおおむね1〜2か月おきに出ており、7.1.0以降にパッチ版は出ていない。 - 使い方は`generate -i 仕様 -g ジェネレーター名 -o 出力先`の1コマンド。生成前に`validate`で仕様の誤りを止められる。 - npm版・pip版もJavaのラッパーで、Java 11以上が要る。Javaを入れたくないならDockerを使う。 - Mavenプラグインで生成したJavaクライアントは、Jackson等の依存を自分のpom.xmlに足さないとコンパイルが通らない。 - OpenAPI 3.1は公式に「beta support」。生成はできるが、実行時に警告が出る。 ## OpenAPI Generatorとは：仕様からSDK・スタブ・ドキュメントを生成するツール OpenAPI仕様は、APIのエンドポイント・パラメーター・レスポンスのスキーマをYAMLまたはJSONで書く標準フォーマットです。OpenAPI Generatorはこの仕様ファイルを読み、言語ごとのテンプレートに流し込んで、対象言語のソースコードやドキュメントを書き出します。公式の[GitHubリポジトリ](https://github.com/OpenAPITools/openapi-generator)は、自らを「API client libraries (SDK generation), server stubs, documentation and configuration」を自動生成するツールと説明しています。 手書きしていたAPIクライアントを仕様から起こすので、フロントエンドとバックエンドが同じ定義を正として分業できます。仕様を先に決めて並行開発する進め方は[スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説](/tech/details/16302/)で扱っています。仕様そのものの書き方は[OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分](/tech/details/10408/)を参照してください。 ### Swagger Codegenからのフォークと現在の関係 OpenAPI Generatorは、Swagger Codegenの`2.4.0-SNAPSHOT`を土台にしたフォークです。最初の安定版3.0.0は[2018年6月1日](https://github.com/OpenAPITools/openapi-generator/releases/tag/v3.0.0)に公開されました。公式の[Fork Q&A](https://openapi-generator.tech/docs/fork-qna/)はフォークの理由として、Swagger Codegen 3.0.0が2.xの設計思想から離れすぎたこと、2.xと3.xの2系統を保守する負担、より速いリリースサイクルを求めたこと、コミュニティが持つロードマップの4点を挙げています。READMEによると、Swagger Codegenの主要コントリビューターとテンプレート作者40人以上が移りました。 Swagger Codegenは今も別プロジェクトとして続いています。[公式のリリース一覧](https://github.com/swagger-api/swagger-codegen/releases)では、v3系が3.0.82（2026年8月4日）、v2系が2.4.52（2026年4月15日）まで出ており、フォーク時に懸念された2系統の保守がそのまま続いています。[公式FAQ](https://openapi-generator.tech/docs/faq/)の説明は「Swagger CodegenはSmartBear主導、OpenAPI Generatorはコミュニティ主導」です。新しく始めるならOpenAPI Generatorを選び、Swagger Codegen 2.xからの移行は[公式の移行ガイド](https://openapi-generator.tech/docs/swagger-codegen-migration/)に沿って進めます。Swagger UIやSwagger EditorなどSmartBear系の周辺ツールは[Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況](/tech/details/17451/)にまとめています。 ## OpenAPI Generatorの使い方：仕様ファイルからのクライアント生成 ここからは、7.26.0のjar（Maven Centralの`openapi-generator-cli-7.26.0.jar`）をTemurin 25で動かした結果です。npm版やHomebrew版でもサブコマンドと引数は同じです。 ### Todo APIの最小仕様ファイル 一覧取得と1件取得の2本だけを持つTodo APIの仕様です。`operationId`は生成されるメソッド名になるので、必ず付けておきます。 ``` openapi: 3.0.3 info: title: Todo API version: 1.0.0 paths: /todos: get: operationId: listTodos responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/Todo' /todos/{id}: get: operationId: getTodo parameters: - name: id in: path required: true schema: type: integer responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Todo' components: schemas: Todo: type: object required: [id, title] properties: id: type: integer title: type: string done: type: boolean ``` ### generateコマンドによるTypeScriptクライアント生成 `-i`に仕様ファイル、`-g`にジェネレーター名、`-o`に出力先を渡します。 ``` java -jar openapi-generator-cli-7.26.0.jar generate \ -i todo.yaml \ -g typescript-fetch \ -o out-ts ``` 出力されたのは次の11ファイルです。`.openapi-generator/FILES`には生成したファイルの一覧、`VERSION`には生成に使った版（7.26.0）が書かれます。 ``` out-ts/.openapi-generator-ignore out-ts/.openapi-generator/FILES out-ts/.openapi-generator/VERSION out-ts/apis/DefaultApi.ts out-ts/apis/index.ts out-ts/docs/DefaultApi.md out-ts/docs/Todo.md out-ts/index.ts out-ts/models/Todo.ts out-ts/models/index.ts out-ts/runtime.ts ``` ### 生成されたコードの中身とtagsの効き方 `models/Todo.ts`には、`required`に入れた`id`と`title`が必須、`done`が省略可のインターフェースとして出ます（コメント行は省略しています）。 ``` export interface Todo { id: number; title: string; done?: boolean; } ``` API側は`operationId`がそのままメソッド名になり、`getTodo(requestParameters: GetTodoRequest, initOverrides?)`が`Promise`を返します。仕様に`tags`を書かないと、全操作が`DefaultApi.ts`にまとまります。各操作に`tags: [todos]`を足して再生成すると、ファイル名は`TodosApi.ts`、クラス名は`TodosApi`に変わりました。APIクラスの分け方はタグで決まるので、仕様を書く段階でタグを揃えておくと、生成後のクラス構成が読みやすくなります。 ### validateによる生成前の仕様検証 わざと`responses`を`responsez`と打ち間違えた仕様で試しました。`validate`は誤りを列挙して終了コード1を返し、`generate`も同じ検証で止まります。 ``` Validating spec (broken.yaml) Errors: - attribute paths.'/todos'(get).responses is missing - attribute paths.'/todos'(get).responsez is unexpected - attribute paths.'/todos/{id}'(get).responsez is unexpected - attribute paths.'/todos/{id}'(get).responses is missing Warnings: - Unused model: Todo ``` `generate`のエラーには`--skip-validate-spec`で検証を外せると出ますが、外すと壊れた仕様のまま生成が通ってしまいます（このケースでも終了コード0で生成されました）。CIでは`validate`を生成の前段に置き、検証を外す運用は避けてください。 ## 生成できるもの：ジェネレーターの種類と成熟度 7.26.0の`list`コマンドが出す既定の一覧（deprecatedを除く）を種類ごとに数えると、次のとおりです。 | 種類 | 数 | うちbeta | うちexperimental | 例 | | ------------- | -- | ------ | -------------- | ----------------------------------------- | | CLIENT | 78 | 16 | 4 | typescript-fetch・python・java・go・csharp | | SERVER | 69 | 19 | 1 | spring・aspnetcore・go-server・kotlin-spring | | DOCUMENTATION | 9 | 2 | 0 | html2・markdown・asciidoc | | SCHEMA | 8 | 6 | 0 | mysql-schema・graphql-schema | | CONFIG | 1 | 0 | 0 | apache2 | 成熟度の区分はソースの[Stability.java](https://github.com/OpenAPITools/openapi-generator/blob/master/modules/openapi-generator-core/src/main/java/org/openapitools/codegen/meta/Stability.java)に定義があります。stableは完成して本番利用できる状態、betaは機能が一部未完成でもメジャー版の間で破壊的変更を避ける状態、experimentalは開発中で、どの版でも非互換の変更や削除があり得るので本番利用は推奨しないと書かれています。`list -s -i`で区分ごとに数えると、stable 117、beta 43、experimental 5、deprecated 6でした。 名前だけで選ぶと外れるものがあります。素の`typescript`と`typescript-nestjs`はexperimental、`python-fastapi`はbeta、`swift5`はdeprecatedです（Swiftは`swift6`が後継）。本番で使うなら`list -i stable`で絞ってから選び、ジェネレーターごとのオプションは`config-help -g typescript-fetch`のように確認します。typescript-fetchでは`npmName`・`withInterfaces`・`stringEnums`・`useSingleRequestParameter`などが出ます。 ## OpenAPI Generatorの導入方法：npm・Docker・Homebrew・pip・jar 公式READMEの導入経路は次の5つが中心です。本体はJavaで動くので、Docker以外はどれもJava 11以上のランタイムが要ります（[公式のInstallation](https://openapi-generator.tech/docs/installation/)に「Java 11 runtime at a minimum」とあります）。 | 経路 | 入れ方 | Java | 向く用途 | | -------- | -------------------------------------------- | ---- | ------------------- | | npm | npm i -D @openapitools/openapi-generator-cli | 必要 | Node.jsのプロジェクトで版を固定 | | Docker | openapitools/openapi-generator-cli | 不要 | Javaを入れたくない環境・CI | | Homebrew | brew install openapi-generator | 必要 | macOSでの常用 | | pip | pip install openapi-generator-cli==7.26.0 | 必要 | Pythonのプロジェクト | | jar | Maven Centralから取得 | 必要 | Javaがある環境・ビルド組み込み | npm版は[公式のラッパー](https://github.com/OpenAPITools/openapi-generator-cli)で、初回実行時に本体のjarをダウンロードして`java`で起動します。Javaの無いmacOSで`npx openapi-generator-cli version`を実行すると、「Unable to locate a Java Runtime.」で失敗しました。Javaを入れられない場合は、`openapitools.json`の`generator-cli`内に`"useDocker": true`を設定すると、ローカルのJavaの代わりにDockerを使えます。この場合、入力パスも`/local/todo.yaml`のようなコンテナ内のパスに変更します。pip版も[PyPIのパッケージ](https://pypi.org/project/openapi-generator-cli/)（7.26.0は2026年10月7日公開）はJavaが前提で、`pip install openapi-generator-cli[jdk4py]`とするとPython 3.10以上でJDKを同梱できます。Dockerの場合は、カレントディレクトリをマウントして実行します。 ``` docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli:v7.26.0 generate \ -i /local/todo.yaml \ -g typescript-fetch \ -o /local/out-ts ``` ### npm版のopenapitools.jsonによる生成エンジンの版固定 npm版を入れると、初回実行時にプロジェクト直下へ`openapitools.json`が作られ、その時点の最新版が書き込まれます。ラッパー2.41.0で試すと`"version": "7.26.0"`が入りました。版を変えるときは`version-manager`を使います。 ``` npx openapi-generator-cli version-manager set 7.25.0 # => Did set selected version to 7.25.0 npx openapi-generator-cli version # => 7.25.0 ``` ラッパー（npmパッケージ）の版と、生成エンジン（jar）の版は別物です。生成結果を左右するのはエンジンの版なので、`openapitools.json`はリポジトリにコミットし、全員とCIが同じ版で生成するようにします。 ## Maven・Gradleプラグインによるコード生成のビルド統合 このMaven例では、先のTodo APIの各操作に`tags: [todos]`を加えた仕様を`src/main/resources/openapi.yaml`に保存し、次の設定を既存のpom.xmlの`build`内の`plugins`に追加します。Mavenでは`openapi-generator-maven-plugin`の`generate`ゴールに、`inputSpec`（仕様ファイル）と`generatorName`（ジェネレーター名）を設定します。 ``` org.openapitools openapi-generator-maven-plugin 7.26.0 generate ${project.basedir}/src/main/resources/openapi.yaml java native com.example.todo.api com.example.todo.model false false ``` Maven 3.9.11で`mvn generate-sources`を実行すると、`target/generated-sources/openapi`に`TodosApi.java`や`Todo.java`など14本のJavaファイルが出ました。生成先のディレクトリはコンパイル対象に自動で加わります。 ### 生成Javaクライアントの依存関係とコンパイルエラー このpom.xmlのまま`mvn compile`すると、BUILD FAILUREになります。「パッケージcom.fasterxml.jackson.databindは存在しません」「パッケージjavax.annotationは存在しません」などが並び、javacの既定の上限である100件でエラー表示が打ち切られました。プラグインはコードを生成するだけで、生成コードが使うライブラリまでは足してくれません。 必要な依存と版は、生成先に一緒に出力される`pom.xml`に書かれています。今回のTodo APIを7.26.0のjava／nativeで生成した例では、次の5つを依存関係に追加するとBUILD SUCCESSになりました。検証用pom.xmlでは、`properties`内に`17`も設定しています。 | groupId | artifactId | 版 | | ------------------------------ | ------------------------- | ------ | | com.fasterxml.jackson.core | jackson-databind | 2.21.6 | | com.fasterxml.jackson.datatype | jackson-datatype-jsr310 | 2.21.6 | | org.openapitools | jackson-databind-nullable | 0.2.12 | | jakarta.annotation | jakarta.annotation-api | 1.3.5 | | com.google.code.findbugs | jsr305 | 3.0.2 | jakarta.annotation-apiが1.3.5（`javax.annotation`パッケージ）なのは、既定ではJakarta EEの名前空間を使わないためです。Spring Boot 3以降と組み合わせる場合のオプション（`useJakartaEe`など）と、okhttp-gson・resttemplate・webclient・restclient・nativeといったライブラリの選び方は[OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで](/tech/details/4098/)で扱っています。Gradleではプラグインid `org.openapi.generator`を適用し、`openApiGenerate`タスクに同じく`generatorName`と`inputSpec`を設定します（[公式のPlugins](https://openapi-generator.tech/docs/plugins/)）。 ## OpenAPI 3.1への対応状況 公式READMEの互換性の記載は「OpenAPI Spec compatibility: 1.0, 1.1, 1.2, 2.0, 3.0, 3.1 (beta support)」で、3.1はベータ扱いです。先のTodo APIを`openapi: 3.1.0`に書き換え、3.1の書き方であるnull許容の型配列`type: [string, "null"]`を持つ`note`プロパティを足して生成すると、次の警告が出ました。 ``` [main] WARN o.o.codegen.DefaultCodegen - OpenAPI 3.1 support is still in beta. To report an issue related to 3.1 spec, please kindly open an issue in the Github repo: https://github.com/openAPITools/openapi-generator. ``` 生成自体は終了コード0で終わり、typescript-fetchでは`note?: string | null;`と正しく型になりました。ただし対応の度合いはジェネレーターごとに違うので、3.1の仕様を使うなら、使うジェネレーターで生成結果の型を確かめてから採用してください。3.0と3.1の書き方の差は[OpenAPIの解説記事](/tech/details/10408/)にあります。 ## 再生成で消える手修正と.openapi-generator-ignore 生成物は再生成のたびに上書きされます。`runtime.ts`の末尾に1行足してから同じコマンドを実行すると、その行は消えました。次に`.openapi-generator-ignore`に`runtime.ts`と書いてから再生成すると、ログに「Ignored …/out-ts/runtime.ts (Ignored by rule in ignore file.)」と出て、手修正が残りました。 ただし、ignoreで固定したファイルは仕様やジェネレーターの版を上げても更新されず、生成された他のファイルとずれていきます。手修正は最後の手段です。先に`config-help`で出るオプション、テンプレートの差し替え、継承やラップによる拡張で済まないかを検討してください。生成物をリポジトリにコミットする運用なら、`.openapi-generator/FILES`の差分で、版を上げたときに増減したファイルを確認できます。 ## リリースの頻度と版の上げ方 フォーク当初は「週次のパッチ、月次のマイナー」を目標に掲げていましたが、直近の配信は違います。[GitHubのリリース一覧](https://github.com/OpenAPITools/openapi-generator/releases)では、7.14.0（2025年6月25日）から7.26.0（2026年10月6日）までの12回の間隔が28〜58日、平均39日でした。Maven Centralに載っている7.x系は7.0.0から7.26.0までで、パッチ版は7.0.1の1本だけです。直近の安定版では、不具合修正も主にマイナー版に含まれています。個別の修正がどの版に入るかは、該当するIssue・PRとリリースノートで確認します。 | 版 | 公開日 | | ------ | ---------- | | 7.26.0 | 2026-10-06 | | 7.25.0 | 2026-08-24 | | 7.24.0 | 2026-07-20 | | 7.23.0 | 2026-06-08 | | 7.22.0 | 2026-04-28 | | 7.21.0 | 2026-03-24 | READMEは7.26.0を「Minor release with breaking changes (with fallback)」と説明しています。マイナー版でも生成結果が変わることがあるという意味です。版を上げるときは、リリースノートの「Breaking changes」を読み、旧版と新版で生成した結果の差分を見てからマージします。READMEの互換表では、次の7.27.0を2026年11月2日に予定しています。 ## OpenAPI Generatorを選ぶ場面と代替ツールに任せる場面 OpenAPI Generatorが強いのは、1つの仕様から複数の言語のクライアントとサーバーを同じ道具で出したいときです。逆に、1つの言語だけで使い、その言語に特化した生成ツールがあるなら、そちらの方が生成コードが言語の慣習に近く、依存も少なく済むことがあります。 | ツール | 対象 | 生成するもの | | ------------------ | ---------- | ------------------ | | OpenAPI Generator | 多言語 | クライアント・サーバー・ドキュメント | | oapi-codegen | Go | クライアントとサーバーの定型コード | | openapi-typescript | TypeScript | 型定義 | | Orval | TypeScript | 型付きのクライアント | | Microsoft Kiota | 多言語 | APIクライアント | 各ツールの位置づけは公式リポジトリの説明に基づきます（[oapi-codegen](https://github.com/oapi-codegen/oapi-codegen)は「Generate Go client and server boilerplate from OpenAPI 3 specifications」、[openapi-typescript](https://github.com/openapi-ts/openapi-typescript)は「Generate TypeScript types from OpenAPI 3 specs」、[Orval](https://github.com/orval-labs/orval)はOpenAPI v3またはSwagger v2から型付きクライアントを生成、[Kiota](https://github.com/microsoft/kiota)はOpenAPIで記述されたAPIのクライアントを生成するCLI）。TypeScriptのフロントエンドだけで型が欲しいならopenapi-typescript、Goのサーバーとクライアントだけならoapi-codegenで足ります。 仕様変更のたびに手修正した生成物が上書きされ、周辺コードの修正まで繰り返す状態なら、コード生成の本格導入は見送ります。仕様が固まらないうちはモックサーバーで仕様を詰めるのが先で、方式は[APIモッキングとは？モックサーバーの方式選定と契約ドリフト対策を実装目線で解説](/tech/details/16308/)にまとめています。コード側から仕様を作るSpring Bootの構成なら、[Springdoc-openapiとは？Spring Boot 3/4での導入方法とバージョン選定を解説](/tech/details/3749/)で仕様を出力し、それをOpenAPI Generatorの入力にする流れになります。仕様からのSDK生成を含むAPIの設計・実装を外部に任せたい場合は、[一想のAPI開発・システム連携](/service/system/api/)でも相談を受けています。 ## よくある質問 ### OpenAPI Generatorは無料で使えますか？生成したコードのライセンスは？ 本体はApache License 2.0のオープンソースで、無料で商用利用できます。READMEは「Generated code is intentionally not subject to the parent project license」と明記しており、生成したコードには本体のライセンスがかかりません。生成コードは利用者のものとして扱われ、保証もありません。 ### Javaを入れずにOpenAPI Generatorを使えますか？ Dockerイメージ`openapitools/openapi-generator-cli`を使えばJavaは不要です。npm版は`openapitools.json`の`useDocker: true`でDocker実行に切り替えられます。pip版は`[jdk4py]`付きで入れるとJDKを同梱できます。それ以外の経路はJava 11以上が必要です。 ### Pythonのクライアントは生成できますか？ `-g python`で生成できます。Todo APIの仕様に`--additional-properties=packageName=todo_client`を付けて生成すると、`pyproject.toml`やテストを含む31ファイルが出ました。Pythonのサーバー側は`python-flask`・`python-aiohttp`のほか、`python-fastapi`（beta）があります。 ### C#・.NET向けには何を使いますか？ クライアントは`csharp`、サーバーは`aspnetcore`や`aspnet-fastendpoints`、Azure Functions向けの`csharp-functions`があります。オプションは`config-help -g csharp`で確認できます。 ### OpenAPI Generatorの公式サイトとドキュメントはどこですか？ 公式サイトは[openapi-generator.tech](https://openapi-generator.tech/)で、ジェネレーターごとのオプション一覧もここにあります。ソースとリリースノートは[GitHubのOpenAPITools/openapi-generator](https://github.com/OpenAPITools/openapi-generator)です。 ## 関連記事 - [OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで](/tech/details/4098/) - [OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分](/tech/details/10408/) - [スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説](/tech/details/16302/) - [Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況](/tech/details/17451/) - [Springdoc-openapiとは？Spring Boot 3/4での導入方法とバージョン選定を解説](/tech/details/3749/) --- 出典: [OpenAPI Generatorとは？使い方・生成されるコード・Maven設定を実行例で解説]()（株式会社一創）