OpenAPI
OpenAPI 仕様 (OAS) は、REST API の記述形式です。 Swagger(英語) は、REST API を作成、文書化、使用するための、この仕様に基づくツールのセットです。 詳細については、「Swagger のドキュメント(英語) 」を参照してください。
IntelliJ IDEA は、YAML および JSON ファイル内の OpenAPI 定義のコーディング支援を提供し、サーバースタブ、クライアントライブラリ（SDK）、OpenAPI 仕様に基づくドキュメントを生成するための Swagger Codegen(英語) との統合を提供します。
エンドポイントツールウィンドウを使用して、OpenAPI 仕様で定義されているすべてのエンドポイントを表示できます。
さらに、定義されたエンドポイントへの HTTP リクエストを OpenAPI 仕様から直接作成し 、組み込みの HTTP クライアントを介して実行できます。
OpenAPI 仕様を作成する
IntelliJ IDEA は、関連する コーディング支援が利用できる専用の OpenAPI 仕様 ファイルタイプを認識します。 これらは、OpenAPI 仕様バージョンの定義を含む通常の YAML または JSON ファイルです。
OpenAPI 仕様を手動で作成する
プロジェクト ツールウィンドウで Alt+Insert を押し、コンテキストメニューから OpenAPI 仕様 を選択します。
ファイルの名前を指定し、仕様バージョンとファイル形式を選択します。
エディターで開いた OpenAPI 仕様では、 
ガターアイコンを使用して仕様セクションをすばやく追加します。
IDE 設定の で 仕様のクイック編集用ガターアイコン チェックボックスを使用して、 ガターアイコンを無効にすることができます。
新しい OpenAPI 仕様ファイルには、形式とバージョンに応じて、次のテンプレートが含まれています。
空の YAML または JSON ファイルから始める場合は、 opnp または swag と入力し、 Tab を押して対応する ライブテンプレートを挿入できます。
URL マッピングに基づいて OpenAPI 仕様を生成する
ソースコードに URL マッピングを含む REST コントローラーがある場合は、コントローラーコードから OpenAPI 仕様をすばやく生成できます。
コントローラーパスの横にある
をクリックします。OpenAPI の下書きを生成 を選択します。
生成されたファイルは に保存されます。
このアクションは、モジュール全体の OpenAPI 仕様を生成できる エンドポイント ツールウィンドウでも使用できます。
別のファイルから定義を参照する
OpenAPI 3.0 では、 $ref(英語) キーワードを使用して、任意の場所でホストされている定義を参照できます。 IntelliJ IDEA は、パスの補完、検証、迅速なナビゲーションを提供します。 完了するために、IntelliJ IDEA は現在のファイルと外部ファイルのコンテキストを理解し、関連する要素へのポインターの使用を提案します。
$refキーワードを入力します。外部定義へのパスの入力を開始します。
Ctrl+B を押すと、参照するファイルと要素にすばやく移動できます。
OpenAPI 仕様をプレビューする
統合された Swagger UI または Redoc UI を使用して、OpenAPI 仕様をプレビューできます。 OpenAPI 仕様ファイルがエディターで開かれている場合、右上隅の 
および 
を使用してプレビューを表示または非表示にします。
Swagger UI と Redoc UI を切り替えるには、プレビュー領域にカーソルを置き、 
をクリックします。
エディターを分割して水平方向にプレビュー
デフォルトで、エディターとプレビューは縦に（並列で）分割されており、ワイド モニターに便利です。 横に分割し、エディターの下部にプレビューを表示することもでき、縦長ディスプレイにより便利です。
エディターの右上隅にある
をクリックして、 エディタープレビュー ペインを開きます。
をクリックして、エディターとプレビューを水平に分割します。
リモート OpenAPI 仕様を追加する
プロジェクトの OpenAPI 仕様で定義したエンドポイント URL は、 コード補完で使用できます。 外部仕様のクライアントコードを記述している場合は、エンドポイント URL を自動補完するためにプロジェクトにファイルとして追加する必要はありません。 関連するリモート仕様へのリンクを追加できます。
設定 ダイアログ（Ctrl+Alt+S ）で、 を選択します。
リモート仕様 リストで
をクリックして、OpenAPI 仕様ファイルの URL を指定するか、 SwaggerHub(英語) で OpenAPI 仕様を見つけます。
を使用して、変更された仕様を再ロードします。
プライベート OpenAPI 仕様(英語)を追加するには、API キーを指定します。
自己ホスト型 SwaggerHub オンプレミス(英語)インスタンスから OpenAPI 仕様を追加するには、インスタンスの URL を指定します。
OpenAPI 仕様の比較
新しい仕様バージョンがある場合は、古いバージョンと比較して、互換性があることを確認する必要があります。 1 つの方法は、 差分 Ctrl+D を見て、変更された行を比較することです。 ただし、すべての変更が互換性にとって重要であるとは限りません。 IntelliJ IDEA は、OpenAPI 仕様の構造を比較し、変更されたパス、パラメーター、応答、互換性を損なう可能性のあるその他の要素の概要を作成できます。
プロジェクト ツールウィンドウで、2 つの OpenAPI 仕様ファイルを選択し、右クリックして OpenAPI 仕様の比較 を選択します。
これにより、変更された仕様要素の要約を含む Markdown ファイルが生成されます。 エディター内でファイルが開き、変更を簡単に移動できるプレビューパネルが表示されます。 最初に選択したファイルと比較して、2 番目に選択したファイルの変更が表示されます。
OpenAPI 仕様からコードを生成する
有効な OpenAPI 仕様を開いている場合、IntelliJ IDEA はそれからコードを生成することを提案します。
ガターの 
をクリックして 実行 'openapi file' を選択します。 IntelliJ IDEA は、指定された場所にソースコードファイルを生成し、ファイルを開くオプション、別のモジュールとしてプロジェクトにインポートするオプションを含む通知を表示します。
Swagger Codegen 実行構成
IntelliJ IDEA は、特定のファイルに対して初めてコード生成を実行するときに、 OpenAPI/Swagger コードジェネレーター 実行構成を作成します。 実行構成を変更するには、 を開いて必要な構成を選択するか、ガターで をクリックして 実行構成の変更 を選択します。
OpenAPI/Swagger コードジェネレーター 実行構成の上部で、次の共通オプションを構成できます。
一般的なパラメーター
項目 | 説明 |
|---|---|
名前(N) | 実行構成の名前を指定して、編集または実行時に他の構成の間ですばやく識別できるようにします。 |
プロジェクトファイルとして保存(S) | 実行構成設定を含むファイルを保存して、他のチームメンバーと共有します。 デフォルトの場所は .idea/runConfigurations です。 ただし、 .idea ディレクトリを共有したくない場合は、プロジェクト内の他のディレクトリに構成を保存できます。 デフォルトでは無効になっており、IntelliJ IDEA は実行構成設定を .idea/workspace.xml に保存します。 |
コード生成設定
項目 | 説明 |
|---|---|
出力ディレクトリ | 生成されたファイルのディレクトリへのパス。 |
コードジェネレーター | コードジェネレーターの種類:
|
言語 | 生成されたコードのターゲット言語。 |
オプションを変更
一部の設定が非表示になっている場合は、 オプションを変更(M) をクリックして表示します。
項目 | 説明 |
|---|---|
仕様のパス | OpenAPI 仕様へのパス。 |
JRE | Swagger Codegen の実行に使用する Java ランタイム |
カスタムテンプレートパス | Mustache テンプレート(英語)のあるディレクトリへのパス。 |
生成パラメーター
ターゲット言語に応じて構成パラメーターを指定します。 詳細については、 swagger-codegen/README.md(英語) を参照してください。
HTTP クライアントで OpenAPI 仕様をテストする
OpenAPI 仕様 ファイルを使用する場合、指定したエンドポイントへの HTTP リクエストを作成し、組み込みの HTTP クライアントを介して実行できます。
エンドポイントへの HTTP リクエストを作成する
OpenAPI 仕様ファイルで、エンドポイント定義の横にあるエディターのガターで
をクリックします。または、 を開き、エンドポイントを右クリックして、 HTTP クライアントでリクエストを生成 を選択します。
IntelliJ IDEA は新しい HTTP リクエストを作成し、 generated-requests.http スクラッチファイルに保存します。
リクエストをエンドポイントにすぐに送信し、保存したくない場合は、 エンドポイント ツールウィンドウの HTTP クライアント タブを使用できます。
IntelliJ IDEA は、利用可能な OpenAPI 仕様に基づいて、リクエスト URL とリクエスト本文 (JSON 形式) の補完を提供します。 これはローカルだけでなく、リモート仕様にも適用されます (補完を有効にするには、 IDE 設定に追加します)。
エンドポイントとその使用箇所の名前を変更する
名前の変更リファクタリングを使用して、定義されたエンドポイントの名前を変更し、HTTP リクエストでの使用を同時に変更します。
以下のいずれかを行います。
OpenAPI 仕様ファイルで、名前を変更するエンドポイントの定義にキャレットを置きます。
HTTP リクエストファイルで、名前を変更する URL パスセグメントにキャレットを置きます。
メインメニューまたはコンテキストメニューから を選択するか、 Shift+F6 を押します。
開いた 名前変更 ダイアログで、新しいエンドポイントの名前を指定します。
プレビューと変更の適用
IntelliJ IDEA は、エンドポイントとその使用箇所の名前を変更します。