統合の OpenAPI 仕様を表示する

Application Integration では、1 つ以上の API トリガーで構成された公開済み統合の OpenAPI 仕様を動的に生成して表示できます。統合の OpenAPI 仕様にアクセスすると、次のことができます。

  • 統合の API エンドポイント、メソッド、データ構造を包括的に理解します。
  • 統合の API の詳細な一元化されたビューを提供することで、開発とトラブルシューティングを効率化します。
  • 統合 API を公開し、会話エージェントとシームレスに統合します。Application Integration で会話エージェントを構築するをご覧ください。

OpenAPI 仕様とは

OpenAPI 仕様のロゴ

OpenAPI 仕様（OAS）は、RESTful API を記述するための言語に依存しない標準形式です。通常は YAML 形式または JSON 形式で記述され、OpenAPI 仕様には、ベース URL、パスと動詞、ヘッダー、クエリ パラメータ、コンテンツ タイプ、リクエスト モデルとレスポンス モデルなど、API 要素の正式な記述が含まれます。OpenAPI 仕様の詳細については、OpenAPI 仕様をご覧ください。

OpenAPI 仕様を生成して表示する

統合の OpenAPI 仕様は、Console の統合エディタから、または API 呼び出しを使用して動的に生成して表示できます。 Google Cloud

始める前に

  • 統合が 1 つ以上の API トリガーで構成されていることを確認します。API トリガーの構成については、API トリガーをご覧ください。
  • 統合を公開します。統合を公開する方法については、統合をテストして公開するをご覧ください。

Open API 仕様を確認する

統合の OpenAPI 仕様を表示するには、次のいずれかのオプションを選択します。

Console

特定の統合の OpenAPI 仕様を表示する手順は次のとおりです。

  1. [Application Integration] ページに移動します。

    Application Integration に移動

  2. ナビゲーション メニューで [統合] をクリックします。

    [統合] ページが開き、 Google Cloud プロジェクトで使用可能なすべての統合が一覧表示されます。

  3. OpenAPI 仕様を表示する統合をクリックします。統合エディタで統合が開きます。
  4. 統合エディタのツールバーで （アクション メニュー）をクリックし、[View OpenAPI spec] を選択します。

    [View OpenAPI spec] ペインが表示され、統合の OpenAPI 仕様が表示されます。生成された OpenAPI 仕様には、デフォルトで統合に構成されているすべての API トリガーが含まれます。

    • 特定の API トリガーの OpenAPI 仕様を表示するには、[APIs] プルダウン リストから API トリガーを選択します。
    • OpenAPI 仕様を YAML ファイルとしてダウンロードするには、[ダウンロード] をクリックします。

API

Application Integration API の generateOpenApiSpec メソッドを使用すると、API 呼び出しを使用して統合の OpenAPI 仕様を表示できます。

同じリージョン内の 1 つ以上の統合の OpenAPI 仕様を表示するには、次の curl コマンドを使用します。

curl -X POST \
    -H "authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
    "apiTriggerResources": [{
    "integrationResource": "INTEGRATION_NAME",
    "triggerId": ["api_trigger/TRIGGER_NAME", "api_trigger/TRIGGER_NAME_2", "api_trigger/TRIGGER_NAME_n"]
    },
    {
    "integrationResource": "INTEGRATION_NAME",
      "triggerId": ["api_trigger/TRIGGER_NAME"]
    }],
    "fileFormat": "DOC_TYPE"
    }' \
    "https://LOCATION-integrations.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:generateOpenApiSpec"

次のように置き換えます。

  • TRIGGER_NAME, TRIGGER_NAME_2, TRIGGER_NAME_n: OpenAPI 仕様を表示する統合内の API トリガーの名前。
  • INTEGRATION_NAME: 統合の名前。
  • DOC_TYPE: 生成するドキュメントのタイプ。サポートされている値は YAML または JSON です。
  • PROJECT_ID: Google Cloud プロジェクトの ID。
  • LOCATION: Google Cloud プロジェクトの場所。

OpenAPI 仕様について

Application Integration は、OpenAPI 仕様 3.0 標準に従って、公開済み統合の OpenAPI 仕様を生成します。次の表に、Application Integration で生成される OpenAPI 仕様の要素を示します。

要素 説明
openapi 使用される OpenAPI 仕様のバージョン。
info 統合に関する情報（名前（タイトル）、説明、公開バージョンなど）。
servers 統合をホストするサーバー URL。
paths パスは、統合で選択した API トリガーごとに作成されます。サーバー URL とパスを組み合わせたものが、API 呼び出しを行うための API エンドポイントになります。

Request フィールドと Response フィールドには、対応する API トリガーに構成された入力変数と出力変数に基づいて値が設定されます。

components schemas フィールドには、API トリガーの入力変数と出力変数の JSON スキーマが含まれます。

securitySchemes フィールドには、API トリガーの認証情報が含まれます。

考慮事項

統合の OpenAPI 仕様を表示する際は、次の点に注意してください。

  • OpenAPI 仕様は、公開された統合に対してのみ生成されます。
  • OpenAPI 仕様は、1 つ以上の API トリガーで構成された統合に対してのみ生成されます。
  • OpenAPI 仕様は、同じリージョンの統合に対してのみ生成されます。
  • OpenAPI 仕様は、デフォルトで YAML 形式で生成されます。OpenAPI 仕様を JSON 形式で生成して表示するには、API 呼び出しで fileFormat パラメータを JSON に設定します。
  • 現在、Application Integration でサポートされている JSON スキーマ キーワードは、次の限られたセットのみです。
    • type
    • items
    • properties
    • description
    • required
    • array
    • object
    • oneOf
    • allOf
    • anyOf
    • not
    • null
    • enum
    • additionalProperties
    • default
  • Swagger エディタを使用して OpenAPI 仕様を検証すると、次の画像のような API パスに関連するセマンティック エラーが発生することがあります。

    Swagger エディタ Swagger エディタ

    これらのエラーは無視して問題ありません。OpenAPI 仕様は引き続き有効です。

次のステップ