查看集成的 OpenAPI 规范

预览版 — 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 文件，请点击 download （下载）。

注意 ：您一次只能从集成编辑器中查看和下载单个集成的 OpenAPI 规范（YAML 格式）。如需查看和下载 OpenAPI 规范（YAML 或 JSON 格式），请按照 API 部分中的说明操作。

API

借助 Application Integration API 的 generateOpenApiSpec 方法，您可以使用 API 调用来查看集成的 OpenAPI 规范。

使用以下 curl 命令查看同一区域中一个或多个集成的 OpenAPI 规范：

提示 ：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: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 规范。
• 系统仅为配置了一个或多个 API 触发器的集成生成 OpenAPI 规范。
• 系统仅为同一区域中的集成生成 OpenAPI 规范。
• 默认情况下，系统以 YAML 格式生成 OpenAPI 规范。如需以 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 触发器。
• 了解测试和发布集成。