查看集成的 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. 在导航菜单中，点击集成。

   系统会显示集成页面，其中列出了 Google Cloud 项目中可用的所有集成。

3. 点击要查看其 OpenAPI 规范的集成。这将在集成编辑器中打开集成。
4. 点击集成编辑器工具栏中的 （操作菜单），然后选择查看 OpenAPI 规范。

   此时会显示查看 OpenAPI 规范窗格，其中显示了集成的 OpenAPI 规范。默认情况下，生成的 OpenAPI 规范包含集成中配置的所有 API 触发器。

   • 如需查看特定 API 触发器的 OpenAPI 规范，请从 API 下拉列表中选择该 API 触发器。
   • 如需将 OpenAPI 规范下载为 YAML 文件，请点击下载。

注意：您一次只能在集成编辑器中查看和下载单个集成的 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 端点。 Request 和 Response 字段会根据为相应 API 触发器配置的输入和输出变量进行填充。 注意：Application Integration 目前仅支持一组有限的 JSON 架构关键字。如需了解支持的关键字，请参阅注意事项。
components	schemas 字段包含 API 触发器的输入和输出变量的 JSON 架构。 securitySchemes 字段包含 API 触发器的身份验证信息。

注意事项

查看集成的 OpenAPI 规范时，请注意以下事项：

• 系统只会为已发布的集成生成 OpenAPI 规范。
• OpenAPI 规范仅针对配置了一个或多个 API 触发器的集成生成。
• 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 Editor 验证 OpenAPI 规范时，您可能会遇到与 API 路径相关的语义错误，如下图所示：

  

  您可以放心地忽略这些错误。OpenAPI 规范仍然有效。

后续步骤

• 使用 Application Integration 构建对话智能体。
• 了解 API 触发器。
• 了解如何测试和发布集成。