查看整合項目的 OpenAPI 規格

Application Integration 可動態產生及查看已發布整合項目的 OpenAPI 規格，這些整合項目已設定一或多個 API 觸發條件。存取整合項目的 OpenAPI 規格，即可：

• 全面瞭解整合項目的 API 端點、方法和資料結構。
• 提供整合 API 的詳細集中檢視畫面，提升開發和疑難排解效率。
• 公開整合 API，並與對話式代理無縫整合，請參閱「使用 Application Integration 建構對話式代理」。

什麼是 OpenAPI 規格？

OpenAPI 規格 (OAS) 是描述 RESTful API 的標準格式，與語言無關。OpenAPI 規格通常以 YAML 或 JSON 格式編寫，可正式描述 API 元素，例如基準網址、路徑和動詞、標頭、查詢參數、內容類型、要求和回應模型等。如要進一步瞭解 OpenAPI 規格，請參閱「OpenAPI 規格」。

注意：Application Integration 僅支援 OpenAPI 規格 3.0.1 版。

生成及查看 OpenAPI 規格

您可以在 Google Cloud 控制台的整合編輯器中，或使用 API 呼叫，動態產生及查看整合的 OpenAPI 規格。

事前準備

• 確認整合作業已設定一或多個 API 觸發條件。如要瞭解如何設定 API 觸發條件，請參閱「API 觸發條件」。
• 發布整合項目。如要瞭解如何發布整合，請參閱「測試及發布整合」。

查看 OpenAPI 規格

如要查看整合的 OpenAPI 規格，請選取下列其中一個選項：

控制台

如要查看特定整合的 OpenAPI 規格，請按照下列步驟操作：

1. 前往「Application Integration」頁面。

   前往 Application Integration

2. 在導覽選單中，按一下「Integrations」(整合)。

   系統隨即會顯示「Integrations」(整合) 頁面，當中列出 Google Cloud 專案中所有可用的整合項目。

3. 按一下要查看 OpenAPI 規格的整合項目。系統會在整合服務編輯器中開啟整合作業。
4. 按一下「Integration editor」工具列中的 (動作選單)，然後選取「View OpenAPI spec」(查看 OpenAPI 規格)。

   「View OpenAPI spec」(查看 OpenAPI 規格) 窗格隨即顯示，當中會列出整合項目的 OpenAPI 規格。根據預設，產生的 OpenAPI 規格會包含整合作業中設定的所有 API 觸發條件。

   • 如要查看特定 API 觸發條件的 OpenAPI 規格，請從「API」下拉式選單中選取 API 觸發條件。
   • 如要將 OpenAPI 規格下載為 YAML 檔案，請按一下「download」(下載)。

注意：在整合編輯器中，您一次只能查看及下載單一整合的 OpenAPI 規格 (YAML 格式)。如要查看及下載 YAML 或 JSON 格式的 OpenAPI 規格，請按照「API」一節中的操作說明操作。

API

Application Integration API 的 generateOpenApiSpec 方法可讓您透過 API 呼叫，查看整合項目的 OpenAPI 規格。

使用下列 curl 指令，查看同一區域中一或多項整合的 OpenAPI 規格：

提示：Linux 和 macOS 作業系統通常會預先安裝 curl。如果沒有 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: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	託管整合的伺服器網址。
paths	系統會為整合中選取的每個 API 觸發條件建立路徑。伺服器網址與路徑結合後，即構成發出 API 呼叫的 API 端點。 系統會根據為對應 API 觸發條件設定的輸入和輸出變數，填入 Request 和 Response 欄位。 注意：Application Integration 目前僅支援一組有限的 JSON 結構定義關鍵字。如要瞭解支援的關鍵字，請參閱「注意事項」。
components	schemas 欄位包含 API 觸發條件輸入和輸出變數的 JSON 結構定義。 securitySchemes 欄位包含 API 觸發條件的驗證資訊。

注意事項

查看整合的 OpenAPI 規格時，請注意下列事項：

• 系統只會為已發布的整合項目產生 OpenAPI 規格。
• 只有設定一或多個 API 觸發條件的整合項目，才會生成 OpenAPI 規格。
• 系統只會為相同區域的整合項目產生 OpenAPI 規格。
• OpenAPI 規格預設會以 YAML 格式生成。如要產生並查看 JSON 格式的 OpenAPI 規格，請在 API 呼叫中將 fileFormat 參數設為 JSON。
• Application Integration 目前僅支援下列一組 JSON 結構定義關鍵字：
  • type
  • items
  • properties
  • description
  • required
  • array
  • object
  • oneOf
  • allOf
  • anyOf
  • not
  • null
  • enum
  • additionalProperties
  • default
• 使用 Swagger 編輯器驗證 OpenAPI 規格時，您可能會遇到與 API 路徑相關的語意錯誤，如下圖所示：

  

  您可以放心忽略這些錯誤。OpenAPI 規格仍然有效。

後續步驟

• 使用 Application Integration 建構對話式代理。
• 瞭解 API 觸發條件。
• 瞭解如何測試及發布整合項目。