根据 OpenAPI 规范创建 API 代理

您正在查看的是 Apigee Edge 文档。
转到 Apigee X 文档
信息

学习内容

通过本教程,您将学会:

  • 根据 OpenAPI 规范创建 Edge API 代理。
  • 使用 cURL 调用 API 代理。
  • 向条件流添加政策。
  • 使用 cURL 测试政策调用。

在本教程中,您将了解如何使用 Apigee Edge 管理界面根据 OpenAPI 规范创建 Edge API 代理。当您使用 HTTP 客户端(例如 cURL)调用 API 代理时,API 代理会向 Apigee 模拟目标服务发送请求。

Open API 计划简介

Open API 计划
“Open API 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需详细了解 Open API 计划,请访问 https://openapis.org

OpenAPI 规范使用标准格式来描述 RESTful API。 OpenAPI 规范采用 JSON 或 YAML 机器可读格式编写,但便于人类阅读和理解。该规范将 API 的此类元素描述为基本路径、路径和动词、标头、查询参数、操作、内容类型、响应描述等。此外,OpenAPI 规范通常用于生成 API 文档。

Apigee 模拟目标服务简介

本教程中使用的 Apigee 模拟目标服务托管在 Apigee 上,并返回简单的数据。它不需要 API 密钥或访问令牌。 实际上,您可以在网络浏览器中访问它。尝试通过点击以下网址访问:

http://mocktarget.apigee.net

目标服务返回问候语 Hello, guest!

如需了解模拟目标服务支持的全套 API,请点击以下网址:

http://mocktarget.apigee.net/help

所需条件

  • Apigee Edge 账号。如果您没有帐号,可以按照创建 Apigee Edge 帐号中的说明进行注册。
  • OpenAPI 规范。在本教程中,您将使用介绍 OpenAPI 模拟目标服务 http://mocktarget.apigee.netmocktarget.yaml OpenAPI 规范。如需了解详情,请参阅 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi
  • 您的机器上安装了 cURL,便于通过命令行或网络浏览器发出 API 调用。

创建 API 代理

Edge

如需使用 Edge 界面根据 OpenAPI 规范创建 API 代理,请执行以下操作:

  1. 登录 https://apigee.com/edge
  2. 在主窗口中点击“API 代理”。

    或者,您可以在左侧导航栏中依次选择开发 > API 代理

    在着陆页上点击“API 代理”

  3. 点击添加代理
    添加 API 代理
  4. 在“创建代理”向导中,针对反向代理(最常见)模板点击使用 OpenAPI 规范
    构建代理类型
  5. 点击从网址导入,然后输入以下信息:
    • OpenAPI 规范网址网址字段中指向 GitHub 上适用于 OpenAPI 规范的原始内容的路径:
      https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
    • 规范名称:OpenAPI 规范的名称,例如 Mock Target(模拟目标)。

      此名称用于在规范存储区中存储 OpenAPI 规范。请参阅管理您的规范

  6. 点击导入

    系统会显示“创建代理”向导中的“详情”页面。这些字段使用 OpenAPI 规范中定义的值预先填充,如下所示

    下表介绍了使用 OpenAPI 规范中的属性预先填充的默认值。表格后面显示了 OpenAPI 规范的摘录,其中说明了所使用的属性。

    字段 说明 默认
    名称 API 代理的名称。例如:Mock-Target-API OpenAPI 规范中的 title 属性,空格替换为短划线
    基本路径 在组织中唯一标识此 API 代理的路径组件。此 API 代理的公开网址由您的组织名称、部署此 API 代理的环境以及此基本路径组成。例如:http://myorg-test.apigee.net/mock-target-api 名称字段内容已转换为全部小写
    说明 API 代理的说明。 OpenAPI 规范中的 description 属性
    目标(现有 API) 代表此 API 代理调用的目标网址。您可以使用任何可通过开放互联网访问的网址。例如:http://mocktarget.apigee.net OpenAPI 规范中的 servers 属性

    下文提供了 OpenAPI 规范的摘录,显示了用于预先填充字段的属性。

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  7. 按如下方式修改说明字段:API proxy for the Apigee mock target service endpoint.
  8. 点击下一步
  9. 通用政策页面的“安全性:授权”下,确保选中直通(无授权),然后点击下一步

    “通用政策”页面上选中了“直通(无授权)”

  10. 在“流”页面上,确保选中所有操作。构建代理流
  11. 点击下一步
  12. 虚拟主机页面上,选择默认安全,然后点击下一步
    在“虚拟主机”页面上选择了“默认”、“安全”选项
  13. 摘要页面上,请确保在可选部署下选中测试环境,然后点击创建和部署

    Apigee 会创建新的 API 代理,并将其部署到您的测试环境:

  14. 点击修改代理以显示 API 代理的“概览”页面。
    模拟目标 API 代理摘要

传统 Edge (Private Cloud)

如需使用传统版 Edge 界面根据 OpenAPI 规范创建 API 代理,请执行以下操作:

  1. 登录 https://apigee.com/edge
  2. 在主窗口中点击“API 代理”。

    或者,您可以在左侧导航栏中依次选择开发 > API 代理

  3. 点击添加代理
    添加 API 代理
  4. 在“创建代理”向导中,选择反向代理(最常见),然后点击使用 OpenAPI
    构建代理类型
  5. 点击从网址导入,为 OpenAPI 规范输入名称,然后在网址字段中输入指向 GitHub 上适用于 OpenAPI 规范的原始内容的路径:

    https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget.yaml
  6. 点击选择
  7. 点击 Next

    系统会显示“创建代理”向导中的“详情”页面。这些字段使用 OpenAPI 规范中定义的值预填充,如下图所示。

    构建代理的详细信息

    下表介绍了使用 OpenAPI 规范中的属性预先填充的默认值。表格后面显示了 OpenAPI 规范的摘录,其中说明了所使用的属性。

    字段 说明 默认
    代理名称 API 代理的名称。例如:Mock-Target-API OpenAPI 规范中的 title 属性,空格替换为短划线
    代理基本路径 在组织中唯一标识此 API 代理的路径组件。此 API 代理的公开网址由您的组织名称、部署此 API 代理的环境以及此基本路径组成。例如:http://myorg-test.apigee.net/mock-target-api 名称字段内容已转换为全部小写
    现有 API 代表此 API 代理调用的目标网址。您可以使用任何可通过开放互联网访问的网址。例如:http://mocktarget.apigee.net OpenAPI 规范中的 servers 属性
    说明 API 代理的说明。 OpenAPI 规范中的 description 属性

    下文提供了 OpenAPI 规范的摘录,显示了用于预先填充字段的属性。

    openapi: 3.0.0
    info:
      description: OpenAPI Specification for the Apigee mock target service endpoint.
      version: 1.0.0
      title: Mock Target API
    paths:
      /:
        get:
          summary: View personalized greeting
          operationId: View a personalized greeting
          description: View a personalized greeting for the specified or guest user.
          parameters:
            - name: user
              in: query
              description: Your user name.
              required: false
              schema:
                type: string
          responses:
            "200":
              description: Success
    ...
    servers:
      - url: http://mocktarget.apigee.net
      - url: https://mocktarget.apigee.net
    ...
    
  8. 按如下方式修改说明字段:API proxy for the Apigee mock target service endpoint.
  9. 点击下一步
  10. 在“流”页面上,确保选中所有操作。构建代理流
  11. 点击下一步
  12. 在“安全性”页面上,选择直通(无)作为安全选项,然后点击下一步
  13. 在“Virtual Hosts”页面上,确保已选择所有虚拟主机,然后点击下一步
  14. 在“构建”页面上,确保选中 test 环境,然后点击构建和部署
  15. 在“摘要”页面上,您会看到确认信息,表明新的 API 代理已成功创建并已部署到测试环境。
    构建代理摘要
  16. 点击 Mock-Target-API 以显示 API 代理的“概览”页面。
    模拟目标 API 代理摘要

恭喜!您已根据 OpenAPI 规范创建 API 代理。接下来,您将对其进行测试,了解其工作情况如何。

测试 API 代理

您可以使用 cURL 或网络浏览器测试 Mock-Target-API API。

在终端窗口中,运行以下 cURL 命令。在网址中替换您的组织名称。

curl http://<org_name>-test.apigee.net/mock-target-api

答案

您应该会看到以下响应:

Hello, Guest!        

做得好!您已根据 OpenAPI 规范构建一个简单的 API 代理并进行了测试。

添加 XML 到 JSON 政策

接下来,您将把 XML 到 JSON 政策添加到查看 XML 响应 条件流,该条件流是在根据 OpenAPI 规范创建 API 代理时自动生成的。此政策会将目标的 XML 响应转换为 JSON 响应。

首先,调用 API,以便将相应结果与您添加政策后收到的结果进行比较。在终端窗口中,执行以下 cURL 命令。您调用目标服务的 /xml 资源,该资源会以原生方式返回一个简单 XML 块。在网址中替换您的组织名称。

curl http://<org_name>-test.apigee.net/mock-target-api/xml

响应

您应该会看到以下响应:

<root> 
  <city>San Jose</city> 
  <firstName>John</firstName> 
  <lastName>Doe</lastName> 
  <state>CA</state> 
</root>

现在,让我们进行一些将 XML 响应转换为 JSON 的操作。将 XML 到 JSON 政策添加到 API 代理中的“查看 XML 响应”条件流。

  1. 点击 Edge 界面中 Mock-Target-API 概览页面右上角的开发标签页。
    “开发者”标签页
  2. 在左侧“导航器”窗格的“代理端点”>“默认”下,点击查看 XML 响应条件流。
    选择“查看 XML 响应”
  3. 点击底部与流的响应相对应的 +步骤按钮。
    选择 +步骤
    此时会打开“添加步骤”对话框,其中显示了可添加的所有政策的分类列表。
  4. 滚动到“中介”类别,然后选择将 XML 转换为 JSON
    “添加步骤”对话框
  5. 保留显示名名称的默认值。
  6. 点击添加。这就将 XML 到 JSON 政策应用到响应。流中的 XML 到 JSON 政策
  7. 点击保存

现在,您已经添加了政策,请使用 cURL 再次调用 API。请注意,您调用的还是同一个 /xml 资源。目标服务仍然返回其 XML 块,但现在 API 代理中的政策会将响应转换为 JSON。进行以下调用:

curl http://<org_name>-test.apigee.net/mock-target-api/xml

请注意,XML 响应将转换为 JSON:

{"root":{"city":"San Jose","firstName":"John","lastName":"Doe","state":"CA"}}

恭喜!您已经成功地测试了添加到条件流的政策的执行。