OpenAPI

OpenAPI 仕様を作成する

GoLand は、関連する コーディング支援を備えた専用の OpenAPI 仕様 ファイルタイプを認識します。 これらは、OpenAPI 仕様バージョンの定義を持つ通常の YAML または JSON ファイルです。

OpenAPI 仕様を手動で作成する

1. プロジェクト ツールウィンドウで Alt+Insert を押し、コンテキストメニューから OpenAPI 仕様 を選択します。

2. ファイルの命名を指定し、仕様バージョンとファイルフォーマットを選択します。

   

エディターで開いた OpenAPI 仕様では、 ガターアイコンを使用して仕様セクションをすばやく追加します。

IDE 設定の 言語 & フレームワーク | OpenAPI 仕様 で 迅速な仕様編集のためのガターアイコン チェックボックスを使用して、 ガターアイコンを無効にすることができます。

形式およびバージョンに応じて、新しい OpenAPI 仕様ファイルには次のテンプレートが含まれます：

空の YAML または JSON ファイルから開始した場合、 opnp または swag と入力し、 Tab を押すことで対応する ライブテンプレートを挿入できます。

別のファイルから定義を参照する

OpenAPI 3.0 では、 $ref(英語) キーワードを使用して、任意の場所でホストされている定義を参照できます。 GoLand は、パス補完、検証、迅速なナビゲーションを提供します。 補完のために、GoLand は現在のファイルおよび外部ファイルのコンテキストを理解し、関連する要素へのポインターの利用を提案します。

1. $ref キーワードを入力します。

2. 外部定義へのパスの入力を開始します。

Ctrl+B を押すと、参照するファイルと要素にすばやく移動できます。

OpenAPI 仕様をプレビューする

統合された Swagger UI または Redoc UI を使用して、OpenAPI 仕様をプレビューできます。 OpenAPI 仕様ファイルがエディターで開かれている場合、右上隅の および を使用してプレビューを表示または非表示にします。

Swagger UI と Redoc UI を切り替えるには、プレビュー領域にカーソルを置き、 をクリックします。

リモート OpenAPI 仕様を追加する

プロジェクトの OpenAPI 仕様で定義したエンドポイント URL は、 コード補完で利用できます。 外部仕様のクライアントコードを記述している場合は、エンドポイント URL を自動補完するためにプロジェクトにファイルとして追加する必要はありません。 関連するリモート仕様へのリンクを追加できます。

1. 設定 ダイアログ（Ctrl+Alt+S ）で、 言語 & フレームワーク | OpenAPI 仕様 を選択します。

2. リモート仕様 リストで をクリックして、OpenAPI 仕様ファイルの URL を指定するか、 SwaggerHub(英語) で OpenAPI 仕様を見つけます。

を使用して、変更された仕様を再ロードします。

プライベート OpenAPI 仕様(英語)を追加するには、API キーを指定します。

自己ホスト型 SwaggerHub オンプレミス(英語)インスタンスから OpenAPI 仕様を追加するには、インスタンスの URL を指定します。

OpenAPI 仕様の比較

新しい仕様バージョンがある場合は、古いバージョンと比較して、互換性があることを確認する必要があります。 1 つの方法は、 差分 Ctrl+D を見て、変更された行を比較することです。 ただし、すべての変更が互換性にとって重要であるとは限りません。 GoLand は、OpenAPI 仕様の構造を比較し、変更されたパス、パラメーター、レスポンス、互換性を損なう可能性のあるその他の要素の概要を作成できます。

OpenAPI 仕様からコードを生成する

有効な OpenAPI 仕様を開いた場合、GoLand はそこからコード生成を提案します：

ガターで をクリックし、 「openapi file」を実行 を選択します。 GoLand は、指定した場所にソースコードファイルを生成し、ファイルを開いたり、プロジェクトに別モジュールとしてインポートするためのオプションを含む通知を表示します。