Visual Studio Code 用 Azure API Center 拡張機能の概要
API Center で API を構築、検出、試行、使用するには、Visual Studio Code 開発環境で Azure API Center 拡張機能を使用できます。
API の構築 - 構築している API を API Center に登録することで、他のユーザーが見つけられるようにします。 統合されたリンティング サポートを使用して、シフトレフト API 設計の適合性を Visual Studio Code にチェックインします。 新しい API バージョンが破壊的変更の検出によって API コンシューマーを中断しないようにします。
API の検出 - API Center で API を参照し、その詳細とドキュメントを表示します。
API の試行 - Swagger UI または REST クライアントを使用して API の要求と応答を調べます。
API の使用 - Microsoft Graph、GitHub などの SDK を生成する Microsoft Kiota エンジンを使用して、JavaScript、TypeScript、.NET、Python、Java などの好みの言語の API SDK クライアントを生成します。
前提条件
Azure サブスクリプション内の 1 つ以上の API Center。 まだ作成していない場合は、「クイック スタート: API センターを作成する」を参照してください。
現時点では、拡張機能を使用して API Center にアクセスするには、共同作成者ロール以上のアクセス許可が割り当てられている必要があります。
Visual Studio Code 用 Azure API Center 拡張機能
Note
特定の機能は、プレリリース バージョンの拡張機能でのみ使用可能であるため、ご注意ください。 Visual Studio Code Marketplace から拡張機能をインストールする場合、リリース バージョンまたはプレリリース バージョンを選択してインストールできます。 拡張機能ビューで拡張機能の [管理] ボタンのコンテキスト メニューを使用して、いつでも 2 つのバージョンを切り替えることができます。
次の Visual Studio Code 拡張機能は省略可能であり、示されている特定のシナリオでのみ必要です。
- REST クライアント拡張機能 - HTTP 要求を送信し、Visual Studio Code で直接応答を表示する
- Microsoft Kiota 拡張機能 - API クライアントを生成する
- スペクトラル拡張機能 - Visual Studio Code でシフトレフト API 設計の準拠チェックを実行する
- Optic CLI - API 仕様ドキュメント間の破壊的変更を検出する
- GitHub Copilot - API コードから OpenAPI 仕様ファイルを生成するため
セットアップ
- Visual Studio Code Marketplace から Visual Studio Code 用 Azure API Center 拡張機能をインストールします。 必要に応じて、オプションの拡張機能をインストールします。
- Visual Studio Code の左側の [アクティビティ] バーで、[API Center] を選択します。
- Azure アカウントにサインインしていない場合は、[Azure にサインイン...] を選択し、プロンプトに従ってサインインします。 API を表示する API Center を含む Azure アカウントを選択します。 表示するサブスクリプションが多数ある場合は、特定のサブスクリプションをフィルター処理することもできます。
API の登録
API を 1 回限り操作として登録するか、CI/CD パイプラインに登録することで、Visual Studio Code から API センターに直接登録します。
- Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Register API」と入力して、Enter キーを押します。
- API Center に API を登録する方法を選択します。
- ステップバイステップは、API の 1 回限りの登録に最適です。
- CI/CD は、ソース管理へのコミットごとに CI/CD ワークフローの一部として実行される、事前構成済みの GitHub または Azure DevOps パイプラインをアクティブな Visual Studio Code ワークスペースに追加します。 API が時間の経過と共に進化し続けているため、API Center で CI/CD を使用して API のインベントリを作成し、仕様やバージョンなどの API メタデータが API Center で最新の状態に保たれるようにすることをおすすめします。
- 登録手順を完了します。
- ステップバイステップでは、API を登録する API Center を選択し、API の登録を完了するための API タイトル、種類、ライフサイクル ステージ、バージョン、仕様などの情報を含むプロンプトに応答します。
- CI/CD の場合は、希望するのソース管理メカニズムに応じて、GitHub または Azure DevOps を選択します。 Azure API Center 拡張機能でパイプラインをワークスペースに追加するには、Visual Studio Code ワークスペースが開いている必要があります。 ファイルが追加されたら、CI/CD パイプライン ファイル自体に記載されている手順を実行して、Azure Pipeline/GitHub Action 環境変数と ID を構成します。 ソース管理にプッシュすると、API が API Center に登録されます。
API 設計の適合性
API の構築時に組織の標準に準拠した設計を確保するために、Visual Studio Code 用 Azure API Center 拡張機能では、Spectral を使用した API 仕様のリンティングの統合サポートが提供されます。
- Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Set active API Style Guide」と入力して、Enter キーを押します。
- 提供されている既定の規則のいずれかを選択するか、組織にスタイル ガイドが既に用意されている場合は、[ローカル ファイルの選択] または [リモート URL の入力] を使用して、Visual Studio Code でアクティブなルール セットを指定します。 Enter キーを押します。
アクティブな API スタイル ガイドが設定されると、OpenAPI または AsyncAPI ベースの仕様ファイルを開くと、Visual Studio Code でローカル リンティング操作がトリガーされます。 結果は、エディターと [問題] ウィンドウ ([表示]>[問題] または Ctrl+Shift+M) の両方にインラインで表示されます。
破壊的変更の検出
新しいバージョンの API を導入する場合は、導入される変更によって、以前のバージョンの API で API コンシューマーが中断されないようにすることが重要です。 Visual Studio Code 用の Azure API Center 拡張機能を使用すると、オプティックを利用した OpenAPI 仕様ドキュメントの破壊的変更検出により、これを簡単に行うことができます。
- Ctrl + Shift + P のキーボード ショートカットを使ってコマンド パレットを開きます。 「Azure API Center: Detect Breaking Change (破壊的変更の検出)」と入力し、Enter キーを押します。
- 比較する最初の API 仕様ドキュメントを選択します。 有効なオプションには、API センターで見つかる API 仕様、ローカル ファイル、または Visual Studio Code のアクティブなエディターが含まれます。
- 比較する 2 つ目の API 仕様ドキュメントを選択します。 有効なオプションには、API センターで見つかる API 仕様、ローカル ファイル、または Visual Studio Code のアクティブなエディターが含まれます。
Visual Studio Code で、2 つの API 仕様間の差分ビューが開きます。 破壊的変更があると、エディターと [問題] ウィンドウ ([表示]>[問題] または Ctrl+Shift+M) の両方にインラインで表示されます。
API コードから OpenAPI 仕様ファイルを生成する
GitHub Copilot と Visual Studio Code 用 Azure API Center 拡張機能を使用して、API コードから OpenAPI 仕様ファイルを作成します。 API コードを右クリックし、オプションから [Copilot] を選択し、[API ドキュメントの生成] を選択します。 これで OpenAPI 仕様ファイルが作成されます。
Note
この機能は API Center 拡張機能のプレリリース バージョンで使用可能です。
OpenAPI 仕様ファイルを生成して正確性を確認したら、[Azure API Center: API の登録] コマンドを使用した API センターで API を登録できます。
API を検出する
API Center のリソースが左側のツリー ビューに表示されます。 API Center のリソースを展開して、API、バージョン、定義、環境、デプロイを確認します。
Apis ツリー ビュー項目に表示されている検索アイコンを使用して、API Center 内の API を検索します。
API ドキュメントの表示
API Center で API 定義のドキュメントを表示し、API 操作を試すことができます。 この機能は、API Center の OpenAPI ベースの API でのみ使用できます。
API Center のツリー ビューを展開して、API 定義を表示します。
定義を右クリックし、[API ドキュメントを開く] を選択します。 API 定義の Swagger UI を含む新しいタブが表示されます。
API を試すには、エンドポイントを選択し、[試してみる] を選択し、必要なパラメーターを入力して、[実行] を選択します。
Note
API によっては、API を試すために認可資格情報または API キーの入力が必要になる場合があります。
ヒント
拡張機能のプレリリースバージョンを使用することで、メンテナンスやエンド ユーザーとの共有が容易な Markdown 形式で API ドキュメントを生成できます。 定義を右クリックし、[Markdown の生成] を選択します。
HTTP ファイルの生成
API Center の API 定義に基づいて、.http ファイルを表示できます。 REST クライアント拡張機能がインストールされている場合は、Visual Studio Code エディターから要求ディレクトリを作成できます。 この機能は、API Center の OpenAPI ベースの API でのみ使用できます。
API Center のツリー ビューを展開して、API 定義を表示します。
定義を右クリックし、[HTTP ファイルの生成] を選択します。 API 仕様によって設定された .http ドキュメントを表示する新しいタブが表示されます。
要求を行うには、エンドポイントを選択し、[要求の送信] を選択します。
Note
API によっては、要求を行うために認可資格情報または API キーの入力が必要になる場合があります。
API クライアントの生成
Microsoft Kiota 拡張機能を使用して、お気に入りの言語用の API クライアントを生成します。 この機能は、API Center の OpenAPI ベースの API でのみ使用できます。
- API Center のツリー ビューを展開して、API 定義を表示します。
- 定義を右クリックし、[API クライアントの生成] を選択します。 Kiota OpenAPI Generator ウィンドウが表示されます。
- SDK に含める API エンドポイントと HTTP 操作を選択します。
- [API クライアントの生成] を選択します。
SDK 名、名前空間、出力ディレクトリに関する構成の詳細を入力します。
生成された SDK の言語を選択します。
クライアントが生成されます。
Kiota 拡張機能の使用の詳細については、「Visual Studio Code 用 Microsoft Kiota 拡張機能」を参照してください。
API 仕様のエクスポート
定義から API 仕様をエクスポートし、ファイルとしてダウンロードできます。
拡張機能のツリー ビューで仕様をエクスポートするには:
API Center のツリー ビューを展開して、API 定義を表示します。
定義を右クリックし、[API 仕様ドキュメントのエクスポート] を選択します。 新しいタブが表示され、そこに API 仕様のドキュメントがレンダリングされます。
また、仕様のエクスポート操作はコマンド パレットから実行することもできます。
- キーボード ショートカットの Ctrl+Shift+P を入力して、コマンド パレットを開きます。
- [Azure API Center: API 仕様ドキュメントのエクスポート] を選択します。
- 対象を選択し、API 定義に移動します。 新しいタブが表示され、そこに API 仕様のドキュメントがレンダリングされます。