根据 OpenAPI 规范创建 API 代理

本页面适用于 Apigee 和 Apigee Hybrid。

查看 Apigee Edge 文档。

学习内容

通过本教程，您将学会：

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

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

Open API 计划简介

“Open API 计划 (OAI) 专注于根据 Swagger 规范创建、改进和推广供应商中立的 API 描述格式。”如需详细了解 Open API Initiative，请参阅 OpenAPI 规范。

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

Apigee 模拟目标服务简介

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

http://mocktarget.apigee.net

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

如需了解模拟目标服务支持的完整 API 集，请参阅 Apigee 示例 API

所需条件

• 开始之前，您必须完成 概览和前提条件中的步骤。
• OpenAPI 规范。在本教程中，您将使用介绍 OpenAPI 模拟目标服务 http://mocktarget.apigee.net 的 mocktarget.yaml OpenAPI 规范。 如需了解详情，请参阅 apigee/api-platform-samples。
• 您的机器上安装了 cURL，便于通过命令行或网络浏览器发出 API 调用。

创建 API 代理

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

1. 如果您使用的是 Cloud 控制台中的 Apigee 界面：选择代理开发 > API 代理。

   如果您使用的是经典版 Apigee 界面：请选择开发 > API 代理，然后在代理窗格中，选择代理的环境。

2. 在主窗口中点击 API 代理。

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

   

3. 点击新建。

   

4. 在创建代理向导中，点击反向代理（最常见）模板的使用 OpenAPI 规范。

   
5. 点击 网址，然后输入以下信息：

   OpenAPI 规范网址：在网址字段中输入的 GitHub 上针对 OpenAPI 规范的原始内容的路径：

   https://raw.githubusercontent.com/apigee/api-platform-samples/master/default-proxies/helloworld/openapi/mocktarget3.0.yaml

6. 点击选择。

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

   

   下表介绍了使用 OpenAPI 规范预填充的值：

   字段	说明	默认
   名称	API 代理的名称。例如：Mock-Target-API。	OpenAPI 规范中的 title 属性，空格替换为短划线
   基本路径	在组织中唯一标识此 API 代理的路径组件。此 API 代理的公开网址由外部域名或内部域名以及此基本路径组成。例如：http://apitest.acme.com/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. 在流页面上，确保选中所有操作。
    提示：条件流是根据 OpenAPI 规范中的 paths 对象内定义的操作自动生成的。条件流会告知 Apigee：“如果您看到此内容，请执行此逻辑”。例如，当 API 调用是 /xml 资源上的 GET （条件）时，请将响应转换为 JSON（通过附加到条件流的政策）。每个事务只执行一个流，即条件为 true 的第一个流。
    
11. 点击下一步。
12. 在摘要页面上，确保已在可选部署下选择了一个环境，然后点击创建和部署：

    

    Apigee 会创建新的 API 代理，并将其部署到您的环境：

13. 点击修改代理，以显示 API 代理的概览页面。

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

测试 API 代理

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

curl -v YOUR_ENV_GROUP_HOSTNAME/myproxy

其中，YOUR_ENV_GROUP_HOSTNAME 是您的环境组主机名。请参阅查找环境组主机名。

例如：

curl -v -k https://apitest.acme.com/myproxy

响应

您应该会看到以下响应：

Hello, Guest!

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

添加 XML 到 JSON 政策

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

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

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

其中，YOUR ENV_GROUP_HOSTNAME 是环境组主机名。请参阅查找环境组主机名。

响应

您应该会看到以下响应：

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

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

注意：Apigee 引入了新版代理编辑器，可让您更轻松地管理代理。

下文前两个标签页中的说明介绍了如何使用新版代理编辑器或经典版代理编辑器。

新版代理编辑器

1. 点击 Apigee 界面的 Mock-Target-API 概览页面中的开发标签页。



2. 在左侧窗格的代理端点 > 默认下，点击查看 XML 响应条件流。
3. 在左侧窗格中，点击政策行中的 + 按钮。

4. 在创建政策对话框中，点击选择政策类型字段，向下滚动到中介，然后选择 XMLtoJSON保留显示名和名称的默认值。

5. 点击创建以创建该政策。

6. 点击响应中查看 XML 响应流旁边的 + 按钮。

   

7. 在添加政策步骤对话框中，点击选择现有政策字段，然后选择 XML 至 JSON-1。

8. 点击添加。这就将 XML 到 JSON 政策应用到响应。

   

   如需查看查看 XML 响应条件流的代码，请点击切换到代码编辑器。

9. 点击保存。

经典版代理编辑器

1. 点击 Apigee 界面的 Mock-Target-API 概览页面中的开发标签页。

   

2. 在左侧导航窗格的代理端点 > 默认下，点击查看 XML 响应条件流。

   

3. 点击底部与流的响应相对应的 +步骤按钮。

   

   此时会打开添加步骤对话框，其中显示了可添加的所有政策的分类列表。

4. 滚动到中介类别，然后选择 XML 到 JSON。

   
5. 保留显示名和名称的默认值。

6. 点击添加。这就将 XML 到 JSON 政策应用到响应。

   
7. 点击保存。

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

curl -v https://YOUR_ENV_GROUP_HOSTNAME/mock-target-api/xml

其中，YOUR ENV_GROUP_HOSTNAME 是环境组主机名。请参阅查找环境组主机名。

请注意，XML 响应将转换为 JSON：

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

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