API 仕様を管理する

このページは Apigee と Apigee ハイブリッドに適用されます。

このドキュメントでは、API Hub で API 仕様を管理する方法について説明します。API 仕様の概要もご覧ください。

API 仕様をバージョンに追加する

1 つ以上の API 仕様を API バージョンに追加できます。次のオプションから選択します。

バージョンの作成時に仕様を追加する

UI のみを使用して、バージョンの作成と同時に API 仕様を追加できます。アクセス可能な仕様の URL を指定するか、システムから仕様ファイルを直接アップロードできます。

コンソール

新しいバージョンに仕様を追加するには:

  1. API バージョンを作成するに記載されている手順に沿って操作を開始します。[新しいバージョンの追加] ページに移動したら、必要に応じて仕様ファイルをバージョンに追加できます。
    1. 仕様ファイルの表示名を入力します。任意の名前を付けることができます。
    2. 仕様ファイルのタイプを選択します。仕様タイプは構成可能なシステム属性です。システム属性もご覧ください。
    3. アクセス可能な有効な API 仕様ファイルを指す URI を指定するか、システム上の API 仕様ファイルを参照します。
    4. （省略可）アップロードされた仕様に厳格な検証を適用する場合は、[エラーを含む仕様ファイルのアップロードを制限する] チェックボックスをオンにします。このオプションを選択すると、検証エラーを含む仕様はアップロードされません。デフォルトでは、エラーを含む仕様がアップロードされます。
  2. [新しいバージョンの追加] ページに入力してから [作成] をクリックします。

既存のバージョンに仕様を追加する

UI または REST API を使用して、既存のバージョンに API 仕様を追加できます。

コンソール

バージョンに仕様を直接追加するには:

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 変更するバージョンの API を探します。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API を選択します。
  5. [仕様ファイルの追加] をクリックします。
  6. 仕様ファイルの表示名を入力します。任意の名前を付けることができます。
  7. 仕様ファイルのタイプを選択します。仕様タイプは構成可能なシステム属性です。システム属性もご覧ください。
  8. アクセス可能な有効な API 仕様ファイルを指す URI を指定するか、システム上の API 仕様ファイルを参照します。
  9. （省略可）アップロードされた仕様に厳格な検証を適用する場合は、[エラーを含む仕様ファイルのアップロードを制限する] チェックボックスをオンにします。このオプションを選択すると、検証エラーを含む仕様はアップロードされません。デフォルトでは、エラーを含む仕様がアップロードされます。
  10. 仕様ファイルを追加するバージョンを選択します。
  11. [作成] をクリックします。

REST

API 仕様をバージョンに追加するには、Add API spec API を使用します。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

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

  • API_PROJECT: API Hub のホスト プロジェクトの名前。API Hub のプロビジョニング時にホスト プロジェクトが選択されました。
  • API_LOCATION: ホスト プロジェクトのロケーション。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: API リソースに関連付けられたバージョンの ID。
  • SPEC_ID: （省略可）仕様の識別子。指定しない場合、システムで生成された ID が使用されます。名前は 4～63 文字の文字列にする必要があり、有効な文字は /[a-z][0-9]-/. です。
  • DATA_FILE or URI: 有効な API 仕様を含む Base64 でエンコードされたファイル、または仕様へのリンク。REST の例をご覧ください。

REST の例

この例では、Base64 でエンコードされた OpenAPI 仕様を使用して、API Hub で新しい仕様を作成します。アップロードすると、API Hub は仕様を解析し、記述的なメタデータと、オペレーションと定義のエンティティのセットが含まれる新しい仕様エンティティを作成します。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

出力例:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

仕様の詳細を返すには:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

出力:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

仕様を一覧表示する

このセクションでは、API バージョンに関連付けられている仕様を一覧表示する方法について説明します。

コンソール

UI で仕様を一覧表示するには:

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. [フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、検査するバージョンを見つけます。
  6. バージョンを選択します。
  7. バージョンにリンクされている仕様は、[仕様ファイル] セクションに一覧表示されます。

REST

API バージョンに関連付けられた仕様を一覧表示するには、List specifications API を使用します。

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

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

  • HUB_PROJECT: API Hub のホスト プロジェクトの名前。このホスト プロジェクトは API Hub のプロビジョニング時に選択されたものです。
  • HUB_LOCATION: ホスト プロジェクトの場所。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: バージョンの一意の ID。

仕様の詳細を取得する

このセクションでは、バージョンに関連付けられている API 仕様の詳細を取得する方法について説明します。

コンソール

UI を使用してデプロイの詳細を表示するには:

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 検査する仕様を含むバージョンの API を探します。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、検査するバージョンを見つけます。
  6. バージョンを選択します。
  7. [仕様ファイル] セクションで、仕様を選択してその詳細を参照します。

REST

仕様の詳細を参照するには、Get specification details API を使用します。

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

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

  • HUB_PROJECT: API Hub のホスト プロジェクトの名前。このホスト プロジェクトは API Hub のプロビジョニング時に選択されたものです。
  • HUB_LOCATION: ホスト プロジェクトの場所。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: バージョンの一意の ID。
  • SPEC_ID: 仕様の一意の ID。

出力例:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

API 仕様を削除する

このセクションでは、バージョンから API 仕様を削除する方法について説明します。仕様を削除すると、関連するオペレーションもバージョンから削除されます。

コンソール

UI を使用して API リソースを削除するには:

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 削除する仕様を含むバージョンの API を見つけます。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、削除する仕様が含まれているバージョンを見つけます。
  6. バージョンを選択します。
  7. [仕様ファイル] セクションで、削除する仕様の行にある [アクション] メニューから [削除] を選択します。
  8. [削除] をクリックします。

REST

API Hub から API リソースを削除するには、Delete API resource API を使用します。

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

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

  • HUB_PROJECT: API Hub のホスト プロジェクトの名前。このホスト プロジェクトは API Hub のプロビジョニング時に選択されたものです。
  • HUB_LOCATION: ホスト プロジェクトの場所。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: バージョンの一意の ID。
  • SPEC_ID: 削除する仕様の一意の ID。

仕様のメタデータを編集する

API Hub に保存されている仕様に関連付けられたメタデータの一部を編集できます。編集可能なメタデータのリストについては、Spec patch API をご覧ください。

コンソール

Google Cloud コンソールから、既存の仕様を変更できます。たとえば、表示名の変更、新しい仕様ファイルのアップロード、ファイルタイプの変更、属性の編集を行うことができます。

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 編集する仕様を含むバージョンの API を見つけます。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、編集する仕様が含まれているバージョンを見つけます。
  6. バージョンを選択します。
  7. [バージョン] ページで、編集する仕様を見つけます。
  8. 編集する仕様の行の [アクション] メニューから、[編集] を選択します。
  9. 仕様編集パネルでは、次のいずれかの仕様メタデータを変更できます。
    • 表示名
    • 仕様ファイルのタイプ
    • 仕様ドキュメント: アップロードする新しい仕様ファイルを参照します。
    • （省略可）アップロードされた仕様に厳格な検証を適用する場合は、[エラーを含む仕様ファイルのアップロードを制限する] チェックボックスをオンにします。このオプションを選択すると、検証エラーを含む仕様はアップロードされません。デフォルトでは、エラーを含む仕様がアップロードされます。
    • ユーザー定義の属性（存在する場合）
  10. [保存] をクリックします。

REST

REST API で仕様を編集するには、以下の手順を踏みます。

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

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

  • HUB_PROJECT: API Hub のホスト プロジェクトの名前。このホスト プロジェクトは API Hub のプロビジョニング時に選択されたものです。
  • HUB_LOCATION: ホスト プロジェクトの場所。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: バージョンの一意の ID。
  • SPEC_ID: 仕様の一意の ID。
  • リクエスト本文: リクエスト本文を使用して、変更する属性を指定します。仕様リソースの定義をご覧ください。

仕様の lint チェックの結果を参照する

API Hub には、API の Open API 仕様を検証する組み込みの（Spectral）リンター（バリデータ）が用意されています。API 仕様を検証するをご覧ください。

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 検査する仕様が含まれているバージョンの API を見つけます。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、検査する仕様が含まれているバージョンを見つけます。
  6. lint 結果列の [結果を表示] をクリックして、lint チェックの結果を参照します。

仕様の内容を取得する

この機能を使用すると、API Hub にアップロードされた仕様の内容を確認できます。

コンソール

UI を使用してデプロイの詳細を表示するには:

  1. Google Cloud コンソールで、[API Hub] ページに移動します。

    [API Hub] に移動
  2. [API] をクリックします。
  3. 削除する仕様を含むバージョンの API を見つけます。[フィルタ] を使用して、API のリストをフィルタするキーワードを指定します。必要に応じて、[検索] を使用して API を探します。
  4. API をクリックして詳細を表示します。
  5. [バージョン] タブで、検査する仕様が含まれているバージョンを見つけます。
  6. 仕様名をクリックすると、その内容が表示されます。

REST

この API は、API Hub にアップロードされた API 仕様の未加工の Base64 でエンコードされたコンテンツを取得します。Get specification contents API を使用します。

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

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

  • HUB_PROJECT: API Hub のホスト プロジェクトの名前。このホスト プロジェクトは API Hub のプロビジョニング時に選択されたものです。
  • HUB_LOCATION: ホスト プロジェクトの場所。この場所は API Hub のプロビジョニング時に選択されたものです。
  • API_ID: API リソースの一意の ID。
  • VERSION_ID: バージョンの一意の ID。
  • SPEC_ID: 仕様の一意の ID。

出力例:

{
  "contents": "Base64-encoded file contents"
}