OpenAPI Generatorは、OpenAPIまたはSwaggerの仕様を、動作するコード（クライアントSDK、サーバスタブ、設定ファイル）に変換するオープンソースツールです。CLIをインストールし、仕様を指定し、typescript-axiosやspringのようなジェネレーターを選択すると、出力フォルダにコードが書き込まれます。このガイドでは、そのインストール方法、利用可能なジェネレーターのリスト表示、複数の言語向けのクライアントとサーバの生成方法について説明します。
OpenAPI Generatorとは
OpenAPI Generatorは、機械可読なAPI記述を読み込み、そこからソースコードを出力します。openapi.yaml（またはJSON）ファイルを与えることで、そのAPIを呼び出すためのクライアントライブラリ、それを実装するサーバスタブ、さらにドキュメントや設定を生成できます。
OpenAPI v2（旧Swaggerフォーマット）とOpenAPI v3の両方をサポートしています。このプロジェクトはGitHubのOpenAPITools組織によってメンテナンスされており、数十の言語とフレームワーク用のテンプレートが用意されています。
重要な違いは、これがコードジェネレーターであり、ドキュメントジェネレーターではないという点です。Swagger UIやRedocのようなドキュメントツールは、仕様を人間が読めるHTMLページにレンダリングします。OpenAPI Generatorは、代わりにコンパイルして出荷するコードを生成します。Markdownドキュメントを出力することもできますが、その主な仕事はSDKとスタブです。
Swagger Codegenとの関連性
Swagger Codegenを使用したことがある方なら、OpenAPI Generatorも馴染み深く感じるでしょう。これは2018年5月に、Swagger Codegenのバージョン2.3.1と2.4.0の間に、40人以上の主要な貢献者とテンプレート作成者によってSwagger Codegenからフォークされました。
このフォークは、Swagger Codegen 3.0.0の方向性に関する意見の相違の後に発生しました。コミュニティは、より迅速でオープンなリリースサイクルを望んでいました。公式のフォークノートでは、このプロジェクトがSwagger Codegen 2.4.0-SNAPSHOTを基盤としていると記述されており、両者は深いルーツを共有しています。どちらを検討すべきか迷っている場合は、Swagger Codegenの代替ツールに関する詳細で実践的な違いが説明されています。
OpenAPI Generatorのインストール
一般的なインストール方法が4つあります。ご自身のスタックに合ったものを選んでください。
npm (最も一般的)
npmラッパーは、ほとんどのチームにとって最も簡単な導入方法です。基盤となるJARファイルをダウンロードして管理してくれます。
npm install @openapitools/openapi-generator-cli -g
グローバルインストールなしで実行することもできます。
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
スタンドアロンJAR
OpenAPI GeneratorはJavaアプリケーションであるため、Maven Centralから直接JARをダウンロードし、Javaで実行できます。これにより、npmやHomebrewのレイヤーを完全に回避できます。
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
ダウンロードする前に、Maven Centralで最新バージョン番号を確認してください。
Docker
公式イメージを使用すると、ローカルに何もインストールせずにコードを生成できます。作業ディレクトリをコンテナにマウントすることで、仕様を読み込み、結果を出力として書き戻すことができます。
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
利用可能なジェネレーターのリスト表示
何かを生成する前に、どのようなジェネレーターが存在するかを確認してください。各ジェネレーターは、java、python、springなどの言語とフレームワークを対象としています。
openapi-generator-cli list
コンパクトな1行ごとの表示にするには、ショートフラグを使用し、カンマで分割します。
openapi-generator-cli list -s | tr ',' '\n'
このリストは、クライアントジェネレーター（API呼び出し用）とサーバジェネレーター（API実装用）を区別し、さらにドキュメントおよびスキーマジェネレーターも含まれています。
クライアントSDKの生成
コアコマンドはgenerateです。常に使用する3つの引数があります。
-i, --input-specは、仕様ファイルまたはURLを指定します。-g, --generator-nameは、実行するジェネレーターを選択します。-o, --outputは、出力ディレクトリを設定します。
AxiosをベースにしたTypeScriptクライアントの例です。
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
これにより、型付きクライアントが./clientに書き込まれます。仕様内の各操作はメソッドになり、各スキーマはモデルになります。
このパターンは複数の言語で機能します。ジェネレーター名と出力フォルダを入れ替えるだけです。
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
コードは単一の仕様から生成されるため、すべてのクライアントは契約と一貫性を保ちます。仕様が変更された場合は、再生成するだけでSDKもそれに追従します。
サーバスタブの生成
サーバジェネレーターは方向を逆転させます。APIを呼び出すコードの代わりに、ルーティング、リクエストモデル、およびハンドラインターフェースが配線された、それを実装する足場（スキャフォールド）が生成されます。あなたはビジネスロジックを記述します。
Spring Bootサーバスタブの例です。
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
生成されたプロジェクトは、仕様に一致するコントローラーとDTOを提供します。インターフェースメソッドを実装するだけで、リクエストとレスポンスの形式はすでに定義されています。これにより、実行中のサーバは公開された契約と一致した状態を保ちます。
出力の設定
デフォルトの出力は、常に希望どおりとは限りません。OpenAPI Generatorにはいくつかの制御機能が用意されています。
追加プロパティ
ほとんどのジェネレーターは、--additional-properties（短縮形は-p）を通じて言語ごとのオプションを公開しています。これらをカンマ区切りのkey=valueペアとして渡します。
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
各ジェネレーターは独自のプロパティを文書化しているため、許容されるキーの完全なリストについてはジェネレーターのページを確認してください。
設定ファイル
コマンドラインが長くなる場合は、オプションを設定ファイルに移動してください。JSONとYAMLの両方がサポートされています。
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
設定ファイルは、生成設定を仕様の隣でバージョン管理に含めることで、ビルドの再現性を高めます。
ファイルの無視
OpenAPI Generatorは、出力ディレクトリ内の.openapi-generator-ignoreファイルを読み込みます。これは.gitignoreと同じ構文を使用します。手動で編集したファイルがジェネレーターによって上書きされるのを防ぐために使用します。
# .openapi-generator-ignore
*.md
src/custom/**
--ignore-file-override <location>を使用すると、別の場所にある無視ファイルを指定できます。
カスタムテンプレート
すべてのジェネレーターはMustacheテンプレートによって駆動されます。デフォルトの出力が社内スタイルに合わない場合は、テンプレートをコピーして編集し、-tで自分のディレクトリを渡してください。
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
これは、カスタムヘッダー、別のHTTPクライアント、または社内の命名規則をすべての生成ファイルに組み込む必要がある場合に適切なツールです。
CIでの実行
コード生成は、一人の開発者のラップトップではなく、パイプラインに属するべきです。仕様が変更されるたびにクライアントを再生成することで、コミットされたSDKが契約からずれることがなくなります。以下はnpxを使用したGitHub Actionsのステップです。
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
再生成された出力がコミットされたものと異なる場合にビルドを失敗させることで、同期が取れていない仕様やSDKを検出できます。
仕様を唯一の信頼できる情報源として維持する
OpenAPI Generatorは、入力する仕様の品質に左右されます。入力がゴミであれば出力もゴミです。曖昧または無効な仕様は、曖昧または壊れたSDKを生成します。したがって、generateを実行する前に最も価値のあるステップが発生します。仕様を正確、完全、かつ安定させることです。
ここでApidogが役立ちます。ApidogはOpenAPIネイティブなオールインワンAPIプラットフォームであり、設計作業と仕様が同じ成果物となります。APIを設計またはインポートすると、ApidogがOpenAPIドキュメントを、他のすべてが派生する唯一の信頼できる情報源として保持します。
クリーンなワークフローは次のようになります。
- ApidogでOpenAPI仕様を設計またはインポートします。ブランチサポートにより、GitによるOpenAPIのバージョン管理と同様に、変更を隔離して作業できます。
- 生成する前に仕様を検証し、Lintを実行します。OpenAPIリンターとSwaggerバリデーターを通過する仕様は、予期せぬ事態が少なく、よりクリーンなコードを生成します。
- 検証済みの仕様をエクスポートし、それをOpenAPI Generatorに渡してSDKとスタブを生成します。
また、OpenAPI仕様をGitHubに同期するなどして、仕様をリポジトリと同期させ、リリース前にOpenAPI diffで変更を確認することもできます。古いツールから移行する場合は、API設計およびテストのためのSwagger代替ツールの比較が良い出発点となります。
Apidogがカバーしない範囲とOpenAPI Generatorがカバーする範囲
ここで正確にしておく価値があります。Apidogは完全なクライアントSDKやサーバスタブを生成しません。それはOpenAPI Generatorの仕事であり、両者は競合するのではなく補完関係にあります。
Apidogは、各エンドポイントに対して、多くの言語とHTTPクライアントで利用できるコピー＆ペースト可能なクライアントリクエストスニペットを提供します。これらはスクリプトに貼り付けられるリクエストごとの例であり、パッケージ化されたSDKではありません。生成されたバージョン管理されたライブラリやサーバのスキャフォールドが必要な場合は、Apidogが生成する仕様に対してOpenAPI Generatorを実行します。
Apidogは、コード生成とは別に、独自のコマンドラインテストランナーであるApidog CLIも提供しています。これはCIでAPIテストを実行します。SDKは生成しません。次のようにインストールして使用します。
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
--access-tokenで認証情報を渡し、-tでテストシナリオを選択し、-eで実行対象の環境を選択し、-rでレポーターを選択します。現在のNode.js LTSリリースで実行してください。セットアップの詳細については、Apidog CLIインストールガイドとコマンドラインからのREST APIテストのチュートリアルを参照してください。
したがって、完全なループは次のようになります。Apidogで仕様を設計および検証し、OpenAPI GeneratorでSDKとスタブを生成し、その後Apidog CLIで実行中のAPIを検証します。
クレジットカード不要でApidogを無料でお試しください。
よくある質問
OpenAPI Generatorとは何ですか？
OpenAPI Generatorは、OpenAPITools組織が提供するオープンソースツールで、OpenAPIまたはSwaggerの仕様からコードを生成します。クライアントSDK、サーバスタブ、ドキュメント、設定ファイルを生成し、OpenAPI v2とv3の両方をサポートします。
OpenAPI Generatorの使い方は？
CLIをインストールし（例: npm install @openapitools/openapi-generator-cli -g）、次に3つのフラグを付けてgenerateを実行します。-iで仕様、-gでジェネレーター、-oで出力フォルダを指定します。まずopenapi-generator-cli listを実行して、利用可能なすべてのジェネレーターを確認してください。
OpenAPI Generatorはどのように動作しますか？
仕様を内部モデルに解析し、選択したターゲット向けのMustacheテンプレートを通じてそのモデルをレンダリングします。各操作はメソッドまたはハンドラーになり、各スキーマは型付きモデルになります。-tを使用してテンプレートをオーバーライドし、出力を変更できます。
OpenAPI仕様からクライアントSDKを生成するには？
クライアントジェネレーターを選択し、generateを実行します。例えば、openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./clientは型付きTypeScriptクライアントを構築します。他の言語をターゲットにするには、typescript-axiosをjava、python、またはgoに置き換えます。
サーバスタブを生成するには？
サーバジェネレーターを選択します。Spring Bootのスキャフォールドの場合、openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-springを実行します。出力には仕様からのコントローラーとリクエストモデルが含まれており、ハンドラーロジックを実装します。
OpenAPI GeneratorとSwagger Codegenの違いは何ですか？
OpenAPI Generatorは、より迅速でコミュニティ主導のリリースサイクルを望む40人以上の貢献者によって、2018年5月にSwagger Codegenからフォークされました。両者は共通の基盤を共有していますが、OpenAPI Generatorは現在、独自のロードマップ、ジェネレーターセット、およびリリーススケジュールを持っています。
OpenAPI仕様からPHP SDKを生成するには？
phpジェネレーターを使用します: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php。生成する前に、openapi-generator-cli listを実行して正確なジェネレーター名を確認し、他のPHPフレームワークオプションも参照してください。