概述

OpenAPI (以前称为 Swagger) 是用于描述和记录 REST API 的开放式标准。 OpenAPI 文档定义 API 支持的资源和操作，包括请求参数和响应数据以及服务器 URL 和认证方法等详细信息。

OpenAPI 文档根据 路径 和 _操作_来描述 REST API。 路径标识可使用 API 访问的特定资源 (例如，酒店预订或客户记录)。 操作 定义可以对该资源执行的特定操作 (例如，创建，检索，更新或删除该资源)。

OpenAPI 文档规定了每个操作的所有细节，包括使用的 HTTP 方法、请求参数、请求正文中包含的数据以及响应正文的结构。

有关 OpenAPI 规范的更多信息，请参阅 OpenAPI 规范。

创建定制扩展时，导入描述外部服务的 REST API 的 OpenAPI 文档。IBM® watsonx™ Assistant 解析 OpenAPI 文档以标识外部服务支持的操作，以及有关每个操作的输入参数和响应以及受支持的认证方法的信息。

完成此处理后，定制扩展将作为可连接到助手的新集成提供。 然后，助手可以使用该扩展根据与客户的对话向外部服务发送请求。 然后，将来自服务的响应中包含的值映射到操作变量，后续操作步骤可以访问这些变量。

(有关将定制扩展连接到助手的更多信息，请参阅 添加定制扩展。)

准备 API 定义

要创建定制扩展，您需要访问描述要与之集成的 REST API 的 OpenAPI 文档。 许多第三方服务发布描述其 API 的 OpenAPI 文档，您可以下载并导入这些文档。 对于贵公司维护的 API，您可以使用标准工具来创建描述该 API 的 OpenAPI 文档。

SwaggerHub Web 站点提供了 OpenAPI 3.0 教程和 工具 来帮助您开发和验证 OpenAPI 文档。 您可以使用联机 Swagger 编辑器 将 OpenAPI 文档转换为正确的格式和 OpenAPI 版本。

OpenAPI 文档必须满足以下需求和限制:

• 该文档必须符合 OpenAPI 3.0 规范。 如果您具有使用较低版本的规范的 OpenAPI (或 Swagger) 文档，那么可以使用联机 Swagger 编辑器 将其转换为 OpenAPI 3.0。

• 文档必须为 JSON 格式 (不支持 YAML)。 如果您具有 YAML 文档，那么可以使用联机 Swagger 编辑器 将其转换为 JSON。

• JSON 脚本中的请求主体必须显示为对象。 例如：

  {
      name: "Bob",
      hobbies: ["sleeping", "eating", "walking"]
  }
  

• 如果您具有 Plus 或更高版本的 watsonx Assistant套餐，那么文档的大小不得超过 4 MB。 但是，如果您有具有数据隔离的 Enteprise 套餐，那么文档的大小不得超过 8 MB。

• content-type 必须为 application/json。

• 要从扩展名流式传输，响应内容类型必须是 text/event-stream。

• 每个操作都必须具有清晰且简明的 summary。 在 UI 中使用摘要文本来描述操作中可用的操作，因此对于正在构建助手的人员而言，摘要文本应该简短且有意义。

• 当前不支持 相对 URL。

• 仅支持 Basic，Bearer，OAuth 2.0和 API 密钥认证。

• 对于 OAuth 2.0 认证，支持以 x- 开头的授权代码，客户机凭证，密码和定制授权类型。 请注意，x- 由 IBM IAM 认证机制 和 watsonx 使用。

• 当前不支持使用 anyOf，oneOf 和 allOf 定义的模式。

遵守响应超时限制

在调用外部 API 时，必须遵守 48 秒的响应超时限制。 定制扩展的超时值不可配置。

构建定制扩展

要基于 API 定义构建定制扩展，请执行以下步骤:

1. 转至 集成 页面。

2. 滚动到“扩展”部分，然后单击 构建定制扩展。

3. 阅读 入门 信息，然后单击 下一步 以继续。

4. 在 基本信息 步骤中，指定有关要创建的扩展的以下信息:

   • 扩展名称: 扩展的简短描述性名称 (例如，CRM system 或 Weather service)。 此名称显示在“集成”页面上扩展的磁贴上，并显示在操作编辑器中的可用扩展列表中。
   • 扩展描述: 扩展及其作用的简要摘要。 该描述可从“集成”页面获取。

   单击下一步。

5. 在 导入 OpenAPI 步骤中，单击或拖动以添加描述要与之集成的 REST API 的 OpenAPI 文档。

   如果尝试导入 JSON 文件时迂到错误，请确保该文件满足 准备 API 定义 中列出的所有需求。 编辑该文件以更正错误或除去不受支持的功能部件。 单击 X 以清除错误消息，然后重试导入。

   成功导入文件后，单击 下一步。

6. 在管理扩展步骤中，您可以查看并根据需要替换导入的OpenAPI文档。 有关替换 OpenAPI 文档的更多信息，请参阅 替换 OpenAPI 文档。

7. 在 认证 选项卡中，您将看到有关 OpenAPI 文档中定义的认证方法的信息。 表。 “认证”选项卡 中的字段提供有关“认证”选项卡中的字段的详细信息:

   字段名称	描述	值
   认证类型	在 OpenAPI 脚本中设置的认证类型。	- OAuth 2.0 - Basic Auth - API key auth - Bearer auth
   用户名	OpenAPI 脚本中的用户名凭证。	例如， user
   密码	在 OpenAPI 脚本中设置的密码凭证。	例如， Password@123
   服务器	指向要连接的开放式 API 文档中定义的服务器的链接。到 API 扩展。	例如， https://custom-extension-server.xyz

8. 复审操作 表显示助手能够从操作步骤调用的操作。 _操作_是使用特定 HTTP 方法（如 GET 或 POST ）对特定资源提出的请求。

   

    For each operation, a row in the table shows the following information:
   

   • 操作: 操作的描述，派生自 OpenAPI 文件中的 summary (如果存在) 或 description。
   • 方法：用于发送操作 API 请求的 HTTP 方法。
   • 资源: 操作对其执行操作的资源的路径。

   要查看有关操作的更多信息，请单击表中其行旁边的 图标。 详情如下：

   • 请求参数: 为操作定义的输入参数的列表，以及每个参数的类型以及参数是必需参数还是可选参数。
   • 响应属性: 映射到助手可访问的变量的响应主体的属性。

9. 如果对扩展名满意，请单击“完成”。

   如果要更改某些内容，请删除扩展，编辑 JSON 文件以进行更改，然后重复导入过程。

现在，新扩展在集成目录的 扩展 部分中作为磁贴提供，您可以 将其添加到助手。