根据 OpenAPI 规范创建 API 代理 | Apigee Edge

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

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.net 的 mocktarget.yaml OpenAPI 规范。如需了解详情，请参阅 https://github.com/apigee/api-platform-samples/tree/master/default-proxies/helloworld/openapi。
您的机器上安装了 cURL，便于通过命令行或网络浏览器发出 API 调用。

创建 API 代理

Edge

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

登录 https://apigee.com/edge。
在主窗口中点击“API 代理”。
或者，您可以在左侧导航栏中依次选择开发 > API 代理。
点击 + 代理。
在“创建代理”向导中，点击反向代理（最常见）模板的使用 OpenAPI 规范。
点击从网址导入，然后输入以下信息：
- OpenAPI 规范网址：在网址字段中输入的 GitHub 上针对 OpenAPI 规范的原始内容的路径：
```
https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml
```
- 规范名称：OpenAPI 规范的名称，例如 Mock Target（模拟目标）。
  此名称用于在规范存储区中存储 OpenAPI 规范。请参阅管理您的规范。

点击导入。

系统会显示“创建代理”向导中的“详情”页面。这些字段使用 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
...

按如下方式修改说明字段：API proxy for the Apigee mock target service endpoint.
点击下一步。
在通用政策页面的“安全性：授权”下，确保选中直通（无授权），然后点击下一步：
在“流”页面上，确保选中所有操作。
提示：条件流是根据 OpenAPI 规范中的 paths 对象内定义的操作自动生成的。条件流会告知 Edge：“如果您看到此内容，请执行此逻辑”。例如，当 API 调用是 /xml 资源上的 GET（条件）时，请将响应转换为 JSON（通过附加到条件流的政策）。每个事务只执行一个流，即条件为 true 的第一个流。
点击下一步。
在虚拟主机页面上，选择默认和安全，然后点击下一步。
在摘要页面上，请确保在可选部署下选中测试环境，然后点击创建和部署：

Apigee 会创建新的 API 代理，并将其部署到您的测试环境：
点击修改代理以显示 API 代理的“概览”页面。

传统 Edge（私有云）

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

登录 https://apigee.com/edge。
在主窗口中点击“API 代理”。
或者，您可以在左侧导航栏中依次选择开发 > API 代理。
点击 + 代理。
在“创建代理”向导中，选择反向代理（最常用），然后点击使用 OpenAPI。
点击从网址导入，输入 OpenAPI 规范的名称，然后输入 GitHub 上 OpenAPI 原始内容的路径。网址字段中的规范：

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

点击下一步。

系统会显示“创建代理”向导中的“详情”页面。这些字段已预先填充使用 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
...

按如下方式修改说明字段：API proxy for the Apigee mock target service endpoint.
点击下一步。
在“流”页面上，确保选中所有操作。
提示：条件流是根据 OpenAPI 规范中的 paths 对象内定义的操作自动生成的。条件流会告知 Edge：“如果您看到此内容，请执行此逻辑”。例如，当 API 调用是 /xml 资源上的 GET（条件）时，请将响应转换为 JSON（通过附加到条件流的政策）。每个事务只执行一个流，即条件为 true 的第一个流。
点击下一步。
在“安全性”页面上，选择通过（无）作为安全设置选项，然后点击下一步。
在“虚拟主机”页面上，确保已选择所有虚拟主机，然后点击 下一步。
在“构建”页面上，确保选中 test 环境，然后点击构建和部署。
在“摘要”页面上，您会看到一条确认信息，告知您新的 API 代理已创建完毕。并将其成功部署到您的测试环境中
点击 Mock-Target-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 响应”条件流。

点击 Edge 界面中“Mock-Target-API 概览”页面右上角的开发标签页。
在左侧导航窗格的“代理端点 > 默认”下，点击查看 XML 响应条件流。
点击底部与流的响应相对应的 +步骤按钮。

此时会打开“添加步骤”对话框，其中显示了可添加的所有政策的分类列表。
滚动到“中介”类别，然后选择 XML 到 JSON。
保留显示名和名称的默认值。
点击添加。这就将 XML 到 JSON 政策应用到响应。
点击保存。

现在，您已经添加了政策，请使用 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"}}

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