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