通过导入 OpenAPI 定义文件来添加 REST API

您可以使用 OpenAPI 定义文件将 REST API 导入到 IBM® API Connect中。

准备工作

您的文件必须符合 OpenAPI 规范的 2.0 或 3.0 版本。 该文件的格式可以是 JSON 或 YAML。

注: 无法验证或发布包含具有 Swagger 属性 (使用 regex ) 的 API 的产品,这些 API 包含诸如 "(?" 之类的前瞻断言。 系统会返回错误消息。 例如:
Product has not been published!
The multipart 'openapi' field contains an OpenAPI definition with validation errors.
    definitions.properties.pattern Does not match format 'regex' (context: (root).definitions.properties.pattern, line: 0, col: 0)
400

关于此任务

您可以使用 API Designer UI 应用程序或使用基于浏览器的 API Manager UI 来完成此任务。

仅限 API 管理器 UI: 要完成此任务,必须为您分配具有 Api-Drafts:EditSettings:ViewApp:View 许可权的角色。 缺省情况下,预先提供的开发者角色具有这些许可权;如果为您分配了定制角色,那么必须具有这些许可权。 有关更多信息,请参阅 创建定制角色

如果您正在使用 API Designer UI ,并且想要使用从其他位置下载的 OpenAPI 定义文件 (例如,从外部 Web 站点下载) ,而不是使用 API Connect创建,请使用此处描述的导入机制,而不是将该文件复制到本地 API Designer 目录中; 导入操作将添加 API Designer所需的 API Connect 特定部分。

过程

要通过导入 OpenAPI 文件来添加 REST API ,请完成以下步骤:

  1. 在导航窗格中,单击 API UI 导航窗格中的 "开发" 图标 开发,然后单击 添加 > API
    这样会显示选择 API 类型屏幕。
  2. 根据 API 要基于的 OpenAPI 规范版本,选择 OpenAPI 2.0OpenAPI 3.0
  3. 在 "导入 "部分,选择 " 现有 OpenAPI ",然后单击 " 下一步 "。
  4. 选择下列其中一种方法来导入文件:
    • 拖放文件

      打开另一个窗口,选择一个文件。 将文件拖至 选择文件 框,然后释放该文件。

    • 浏览以查找文件

      单击 选择文件 框。 找到该文件并将其选中。

    • 指定文件的 URL

      或指定文件 URL 字段中,键入或粘贴文件的 URL。 (可选) 添加 用户名密码 (如果访问文件需要这些用户名和密码)。

    如果以下文件类型包含有效的 OpenAPI 定义,那么支持这些文件类型: .json.yml.yaml
  5. 单击 下一步 以导入所选文件。

    向导会检查 YAML 的有效性,并显示一条消息以指示验证成功。

    注:
    • 如果您正在使用 API Manager UI ,那么如果文件定义的 API 具有与现有 API 定义相同的名称和版本,那么导入操作将失败。 但是,如果您使用的是 API Designer UI ,那么 API 定义由本地文件系统中的文件名唯一标识; 因此,如果导入定义相同 API 名称和版本的两个不同文件,那么将在 API Connect中创建两个具有相同名称和版本的 API 定义,并且不会发生任何错误。
    • 任何验证错误消息均仅以英语显示,未进行翻译。
  6. 可选: 如果要立即使用 API 进行进一步开发和测试,请选择 激活 API
    注:
    • 选择 激活 API 选项时, API Connect 会自动完成以下操作:
      • 创建草稿产品,将 API 添加到该产品,并将该产品发布到沙箱目录以便可以调用该 API。 产品标题为 api_title 自动产品。 此产品在开发视图中不可见,您无法直接删除。 但是,如果删除 API ,那么会将草稿产品与 API 一起删除; 请参阅 删除 API 定义。 该产品在它发布至的任何目录中可见。 如果要从目录中除去产品,那么必须单独执行此操作; 请参阅 从目录中除去产品
      • 为产品预订沙箱测试应用程序,以便立即在测试环境中对 API 进行测试。 有关测试 API 的信息,请参阅 测试 API
    • 如果在 "沙箱" 目录中针对 "阶段" , "发布" 或 "替换" 操作启用了生命周期核准,那么不能使用 激活 API 选项。 如果启用了任何此类生命周期核准,那么为了能够使用 激活 API 选项,必须将其禁用; 有关生命周期核准设置的信息,请参阅 创建和配置目录
    • 要使用 激活 API 选项,必须为您分配具有 Product:ManageSubscription:Manage 许可权的角色。 缺省情况下,预先提供的开发者角色具有这些许可权;如果为您分配了定制角色,那么必须具有这些许可权。 有关更多信息,请参阅 创建定制角色
  7. 单击下一步导入 API 摘要 面板指示 YAML 文件已装入且有效。

    如果已选择激活 API,那么向导会填充 API 端点 URL,并显示可供您使用的客户机标识和客户机密钥。

  8. 选择以下某个选项:
    • 要进一步配置 API,请单击编辑 API。 有关详细信息,请参阅 编辑 API 定义
    • 如果此时不想要进一步配置 API,请单击面包屑跟踪中的开发链接,以返回到欢迎页面;随后即可立即继续处理其他任务。 有关以后如何配置 API 的详细信息,请参阅 编辑 API 定义

结果

导入 API 定义后,它会显示在开发页面中的“API 定义”列表中。 对于 API Designer, API 和产品的规范存储在您登录时指定的目录中。 对于 API Manager, API 和产品的规范存储在管理服务器上。

后续操作

通过将 API 包含在产品中,然后将该产品发布到目录中,应用程序开发人员就可以使用这些 API。 有关更多信息,请参阅 使用产品使用目录