Visual Studio Code 用 Azure API Center 拡張機能を使用して API を管理する
API ガバナンスの取り組みを最大限に成功させるためには、API 開発サイクルの早い段階でガバナンスをシフトレフトさせることが重要です。 このアプローチにより、API 開発者は最初から API を正しく作成でき、開発作業の無駄を省き、開発プロセスの後半で生じる非準拠 API を削減することができます。
Visual Studio Code 用 Azure API Center 拡張機能には、API 開発者向けの次のガバナンス機能が含まれています。
- API が Visual Studio Code で開発される際に、API スタイル ガイドに照会して API 設計を評価します。
- API が信頼性を維持し、期待通りに機能し、エンド ユーザーと利害関係者の信頼を維持できるよう、破壊的変更を早期に検出します。
API 開発者は拡張機能の機能を利用して、API センターで API を登録し、API を検出して使用することもできます。
前提条件
Azure サブスクリプション内の 1 つ以上の API Center。
- 現時点では、拡張機能を使用して API を管理するには、API センターに対する Azure API Center サービス共同作成者ロール以上のアクセス許可を割り当てる必要があります。
- Visual Studio Code のスペクトラル拡張機能 - Visual Studio Code でシフトレフト API 設計の準拠チェックを実行する
- Optic CLI - API 仕様ドキュメント間の破壊的変更を検出する
セットアップ
Visual Studio Code Marketplace から Visual Studio Code 用 Azure API Center 拡張機能をインストールします。 必要に応じて、他の拡張機能をインストールします。
Note
注記がある一部の機能は、Azure API Center 拡張機能のプレリリース バージョンでのみ使用できます。 Visual Studio Code Marketplace から拡張機能をインストールする場合、リリース バージョンまたはプレリリース バージョンを選択してインストールできます。 拡張機能ビューで拡張機能の [管理] ボタンのコンテキスト メニューを使用して、いつでも 2 つのバージョンを切り替えることができます。
Visual Studio Code の左側の [アクティビティ] バーで、[API Center] を選択します。
Azure アカウントにサインインしていない場合は、[Azure にサインイン...] を選択し、プロンプトに従ってサインインします。 API を表示させる API Center を含む Azure サブスクリプションを選択します。 表示するサブスクリプションが多数ある場合は、特定のサブスクリプションをフィルター処理することもできます。
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 拡張機能を使用すると、Optic を利用した 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) の両方に表示されます。
