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リポジトリは、自らを「API client libraries (SDK generation), server stubs, documentation and configuration」を自動生成するツールと説明しています。

手書きしていたAPIクライアントを仕様から起こすので、フロントエンドとバックエンドが同じ定義を正として分業できます。仕様を先に決めて並行開発する進め方はスキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説で扱っています。仕様そのものの書き方はOpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分を参照してください。

Swagger Codegenからのフォークと現在の関係

OpenAPI Generatorは、Swagger Codegenの2.4.0-SNAPSHOTを土台にしたフォークです。最初の安定版3.0.0は2018年6月1日に公開されました。公式のFork Q&Aはフォークの理由として、Swagger Codegen 3.0.0が2.xの設計思想から離れすぎたこと、2.xと3.xの2系統を保守する負担、より速いリリースサイクルを求めたこと、コミュニティが持つロードマップの4点を挙げています。READMEによると、Swagger Codegenの主要コントリビューターとテンプレート作者40人以上が移りました。

Swagger Codegenは今も別プロジェクトとして続いています。公式のリリース一覧では、v3系が3.0.82（2026年8月4日）、v2系が2.4.52（2026年4月15日）まで出ており、フォーク時に懸念された2系統の保守がそのまま続いています。公式FAQの説明は「Swagger CodegenはSmartBear主導、OpenAPI Generatorはコミュニティ主導」です。新しく始めるならOpenAPI Generatorを選び、Swagger Codegen 2.xからの移行は公式の移行ガイドに沿って進めます。Swagger UIやSwagger EditorなどSmartBear系の周辺ツールはSwaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況にまとめています。

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<Todo>を返します。仕様に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を除く）を種類ごとに数えると、次のとおりです。

成熟度の区分はソースの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に「Java 11 runtime at a minimum」とあります）。

npm版は公式のラッパーで、初回実行時に本体の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のパッケージ（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（ジェネレーター名）を設定します。

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.26.0</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
        <generatorName>java</generatorName>
        <library>native</library>
        <apiPackage>com.example.todo.api</apiPackage>
        <modelPackage>com.example.todo.model</modelPackage>
        <generateApiTests>false</generateApiTests>
        <generateModelTests>false</generateModelTests>
      </configuration>
    </execution>
  </executions>
</plugin>

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内に<maven.compiler.release>17</maven.compiler.release>も設定しています。

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・ライブラリ選択までで扱っています。Gradleではプラグインid org.openapi.generatorを適用し、openApiGenerateタスクに同じくgeneratorNameとinputSpecを設定します（公式の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の解説記事にあります。

再生成で消える手修正と.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のリリース一覧では、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とリリースノートで確認します。

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つの言語だけで使い、その言語に特化した生成ツールがあるなら、そちらの方が生成コードが言語の慣習に近く、依存も少なく済むことがあります。

各ツールの位置づけは公式リポジトリの説明に基づきます（oapi-codegenは「Generate Go client and server boilerplate from OpenAPI 3 specifications」、openapi-typescriptは「Generate TypeScript types from OpenAPI 3 specs」、OrvalはOpenAPI v3またはSwagger v2から型付きクライアントを生成、KiotaはOpenAPIで記述されたAPIのクライアントを生成するCLI）。TypeScriptのフロントエンドだけで型が欲しいならopenapi-typescript、Goのサーバーとクライアントだけならoapi-codegenで足ります。

仕様変更のたびに手修正した生成物が上書きされ、周辺コードの修正まで繰り返す状態なら、コード生成の本格導入は見送ります。仕様が固まらないうちはモックサーバーで仕様を詰めるのが先で、方式はAPIモッキングとは？モックサーバーの方式選定と契約ドリフト対策を実装目線で解説にまとめています。コード側から仕様を作るSpring Bootの構成なら、Springdoc-openapiとは？Spring Boot 3/4での導入方法とバージョン選定を解説で仕様を出力し、それをOpenAPI Generatorの入力にする流れになります。仕様からのSDK生成を含むAPIの設計・実装を外部に任せたい場合は、一想の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で、ジェネレーターごとのオプション一覧もここにあります。ソースとリリースノートはGitHubのOpenAPITools/openapi-generatorです。

関連記事

• OpenAPI GeneratorでJavaコードを自動生成する方法｜CLI導入からSpring・ライブラリ選択まで
• OpenAPIとは？Swaggerとの違いと仕様書(YAML/JSON)の書き方｜3.0・3.1・3.2の差分
• スキーマファーストとは？OpenAPI起点の並行開発と破壊的変更検知を解説
• Swaggerとは：Editor・UIをDockerで動かす手順とOpenAPI 3.2対応の現況
• Springdoc-openapiとは？Spring Boot 3/4での導入方法とバージョン選定を解説