統合の OpenAPI 仕様を表示する

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

統合の API エンドポイント、メソッド、データ構造を包括的に理解する。
統合の API の詳細を一元的に表示することで、開発とトラブルシューティングを効率化できます。
統合 API を公開し、Google Cloud 会話エージェントなどの会話エージェントとシームレスに統合します。

OpenAPI 仕様とは？

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

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

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

始める前に

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

OpenAPI 仕様を表示する

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

Console

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

[Application Integration] ページに移動します。
Application Integration に移動
ナビゲーションメニューで [統合] をクリックします。
[統合] ページが開き、 Google Cloud プロジェクトで使用可能なすべての統合が一覧表示されます。
OpenAPI 仕様を表示する統合をクリックします。統合エディタで統合が開きます。
統合エディタのツールバーで more_vert（アクションメニュー）をクリックし、[OpenAPI 仕様を表示] を選択します。
[OpenAPI 仕様を表示] ペインが表示され、統合の OpenAPI 仕様が表示されます。生成された OpenAPI 仕様には、デフォルトで統合で構成されたすべての API トリガーが含まれます。
- 特定の API トリガーの OpenAPI 仕様を表示するには、[API] プルダウンリストから API トリガーを選択します。
- OpenAPI 仕様を YAML ファイルとしてダウンロードするには、[ ダウンロード ] をクリックします。

API

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

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

ヒント: curl は通常、Linux と macOS のオペレーティングシステムにプリインストールされています。curl を所有していない場合は、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/integrations/-: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 仕様のみを表示できます。

OpenAPI 仕様の概要

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

要素	説明
`openapi`	使用されている OpenAPI 仕様のバージョン。
`info`	統合に関する情報（名前（タイトル）、説明、公開バージョンなど）。
`servers`	統合をホストするサーバー URL。
`paths`	パスは、統合で選択した API トリガーごとに作成されます。サーバー URL とパスを組み合わせたものが、API 呼び出しを行う API エンドポイントになります。 `Request` フィールドと `Response` フィールドには、対応する API トリガーに構成された入力変数と出力変数に基づいて値が入力されます。注: 現在、Application Integration は、限定された一連の JSON スキーマキーワードのみをサポートしています。サポートされているキーワードについては、考慮事項をご覧ください。
`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 Editor を使用して OpenAPI 仕様を検証すると、次のような API パスに関連するセマンティックエラーが発生することがあります。

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