API ガバナンス

オンラインで編集する

API Governanceツールは、 OpenAPI ドキュメントをスペクトルルールセットに対して検証する。

このツールは、 API Connect の API ガバナンス機能を API Agent から利用できるようにするために提供されています。 例えば、 OpenAPI ドキュメントをスペクトルルールセットに対して検証する。 また、 OpenAPI 3.0 ドキュメント内のスペクトル検証の発見を修正（リメディエーション）するために使用することもできる。

ツールの詳細と制限

以下はAPI Governanceツールの詳細と制限事項である：
  • このツールをオンプレミスの API Connect で使用するには、管理 CR で API Governance を有効にします。
  • 現在、API Governanceツールは、APIガバナンスサービスにおけるルールセットの最新バージョンの作業をサポートしている。 たとえば、 OpenAPI 文書を最新バージョンのルールセットで検証することができる。 ただし、プロンプトを使用する場合は、古いバージョンを指定することはできない。 この制限は、 OpenAPI 文書の検証所見を修正するための修正操作にも適用される。
  • このツールの（ルールセットによる）修復操作は、AIベースの修復を使用するため、時間がかかることがある。 この時間は、より大きく、より複雑な OpenAPI ドキュメントではより長くかかる。 デフォルトで3分間のタイムアウトが適用される。 OpenAPI、修復に3分以上かかる場合、ツールはタイムアウトします。
  • 最大3分間の修復に対応するため、クラスタのIngressコントローラ、Ingress Route、または HAProxy のタイムアウト設定が3分未満でタイムアウトしないことを確認してください。
API ガバナンスの以下の機能は、 API Agent で利用可能である：

ルールセット一覧

プロバイダー組織内の API Governance の一部として提供されるスペクトルルールセットをリストアップできます。

テーブルには、ルールセットに関する以下の詳細が表示される：
  • 名前
  • バージョン
  • 説明
プロンプトの例
List rulesets
次のアクションを提案
  • ルールセットを使用して、 {@filename} を検証する。 {ruleset}
  • ルールセットを使用して、api {draft-api-name} : {draft-api-version} を検証する。 {ruleset}

ルールセットのルールを一覧表示する

プロバイダ組織内で利用可能なスペクトルルールセットの一部である個々のルールをすべて一覧表示できます。

  • 指定されたルールセット内の各ルールについて、以下の詳細が表に表示される：
    • 名前
    • 説明
表 1. パラメータ
パラメーター 必須 説明 デフォルト
ruleset はい ルールを一覧表示したいルールセット名。 なし
プロンプトの例
List rules in ruleset {ruleset}
次のアクションを提案
  • ルールセットを使用して、 {@filename} を検証する。 {ruleset}
  • ルールセットを使用して、api {draft-api-name} : {draft-api-version} を検証する。 {ruleset}

ルールセットを使用して OpenAPI ドキュメントを検証する

プロバイダ組織では、以下のオプションを使用して、 OpenAPI 文書をスペクトルルールセットで検証できます：
  • Visual Studio Code プラグイン チャットウィンドウでローカルファイル添付アップロードを使用する。
  • ユーザのプロバイダ組織内の既存のドラフトAPIの名前とバージョンを API Managerに提供する。

この操作により、以下の詳細が表示される：

  • スペクトル所見の数とその重症度を簡単にまとめたもの。
  • 検証レポート。以下の調査結果のすべてを含む、ダウンロード可能な CSV ファイル：
    • ルールとルールセット
    • ルールに違反する検証結果を示すメッセージ。
    • OpenAPI 文書の行番号は所見に対応する。
    • OpenAPI ドキュメント内の発見の場所（JSON パス）。
  • 次のスクリーンショットに示すように、調査結果とその場所も 「PROBLEMS」 パネルに表示されます。

  • OpenAPI ドキュメントがローカルファイルの場合、自動的に Visual Studio Code ファイルエディターで開きます。 すべてのスペクトル所見はファイル内でハイライトされている。
表 2. パラメータ
パラメーター 必須 説明 デフォルト
input_file いいえ 検証されるYAMLまたはJSON形式の OpenAPI。 なし
api_name いいえ 検証されるドラフトAPIの名前(info.x-ibm-name)。 なし
api_version いいえ 検証されるドラフトAPIのバージョン(info.version)。 なし
ruleset はい バリデーションで使用するルールセットのリスト。 なし
プロンプトの例
1つのルールセットに対してローカルファイルを検証するには、以下のプロンプトを実行する：
validate api {@filename} using {ruleset} ruleset
2つ以上のルールセットに対してローカルファイルを検証するには、次のプロンプトを実行します
Validate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
ドラフトAPIを1つのルールセットに対して検証するには、以下のプロンプトを実行する
Validate api {api-name}:{api-version} using {ruleset} ruleset
ドラフトAPIを複数のルールセットに対して検証するには、以下のプロンプトを実行する
Validate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
次のアクションを提案
  • ルールセットを使用して、API {@filename} を修復する。 {ruleset}
  • ルールセットを使用して、 {@filename} を再検証する。 {ruleset}

それとも

  • ルールセットを使用して、api {draft-api-name} : {draft-api-version} を修復する。 {ruleset}
  • ルールセットを使用して、api {draft-api-name} : {draft-api-version} を再検証する。 {ruleset}

ルールセットを使用している OpenAPI 文書を修復（修正）する

API Governance による OpenAPI ドキュメントの検証で、プロバイダー組織内のスペクトル・ルールセットに基づく所見が明らかになった場合、AI ベースの修復を使用して、これらの所見の解決を試みることができる。 Visual Studio Code プラグインチャットウィンドウでローカルファイルをアップロードするか、 API Manager で既存のドラフト API を指定します。

この操作により、以下の詳細が表示される：

  • OpenAPI ダウンロード可能なドキュメントファイルには、選択されたルールセットに対してAIベースの修復が自動的に修復できた、適用されたすべての修復が含まれています。

  • また、修復された OpenAPI ドキュメントファイルは、自動的に Visual Studio Code ファイルエディタで開きます。 適用された修正はファイル内で直接ハイライトされる。

  • 適用された各修正の詳細は、 「AI RECOMMENDATIONS」 パネルに以下のように表示されます：

    • 推薦文へのパス（JSONパス
    • 推薦文（説明文）
    • 説明（推奨事項を説明する）
    • 推奨の元となったスペクトル・ルールの詳細（重大度、ルールセット名、ルール名、メッセージ）。
注:
  • AIベースの修復は、API Governanceのspectral-owaspおよびspectral-oasルールセットでのみサポートされています。 サポートされていないルールセットを使用して修復を促された場合、 API Agent からのチャット応答でサポートされていないルールセットが使用されていないという警告が表示されます。
  • このツールは、有効な OpenAPI 3.0 ドキュメントが入力として使われることを想定している。 無効なファイルが与えられても警告は出ない。 たとえば、 OpenAPI 文書に適用されるルールを持つルールセットに対して、 AsyncAPI 文書を入力として供給する、あるいはその逆。
  • 同じ OpenAPI ドキュメントに対して複数回修復を実行し、問題が最初に見つからなかった場合に修復することができます。
  • AIによって修正を適用すると、他のスペクトルルールに新たな違反が発生する可能性がある。なぜなら、システムは各変更の後に、その修正と推奨をルールセットに対して自動的に検証しないからである。
表 3. パラメータ
パラメーター 必須 説明 デフォルト
input_file いいえ OpenAPI YAML または JSON 形式の仕様。 なし
api_name いいえ 修正されるドラフトAPIの名前(info.x-ibm-name)。 なし
api_version いいえ 改善されるドラフトAPIのバージョン(info.version)。 なし
ruleset はい 修復に使用するルールセットのリスト。 なし
プロンプトの例
ルールセットに対してローカルファイルを修復するには、以下のプロンプトを実行する：
Remediate api {@filename} using {ruleset} ruleset
2つ以上のルールセットに対してローカルファイルを修復するには、以下のプロンプトを実行する：
Remediate api {@filename} using rulesets {ruleset-1}, {ruleset-2}
単一のルールセットに対してドラフトAPIを修復するには、以下のプロンプトを実行する：
Remediate api {api-name}:{api-version} using {ruleset} ruleset
複数のルールセットに対してドラフトAPIを修復するには、以下のプロンプトを実行する：
Remediate api {api-name}:{api-version} using Rulesets {ruleset-1}, {ruleset-2}
次のアクションを提案
  • ルールセットを使用して、API {@filename} を再修正する。 {ruleset}
  • ルールセットを使用して、 {@filename} を検証する。 {ruleset}

それとも

  • ルールセットを使用して、api {draft-api-name} ： {draft-api-version}。 {ruleset}
  • ルールセットを使用して、api {draft-api-name} : {draft-api-version} を検証する。 {ruleset}