创建 OpenAPI 规范

您正在查看 Apigee Edge 文档。
前往 Apigee X 文档
信息

在本教程中,您将创建一个 OpenAPI 规范来为调用目标服务器的 API 建模。目标服务器由一个非常简单的基于 Node.js 的服务器组成,您可以在自己的机器上创建和运行该服务器。完成本教程大约需要 10 分钟。

学习内容

在本教程中,您将学习如何:

所需条件

您需要满足以下条件才能开始使用:

创建一个简单的 Node.js 服务器

如需创建简单的 Node.js 服务器,请执行以下操作:

  1. 创建一个名为 index.js 的文件。
  2. 将以下 Node.js 代码复制到该文件中:

    var express = require('express');
    var app = express();  
    
    app.get('/v1/hello', function (req, res) {
      res.setHeader("Access-Control-Allow-Origin", "*");
      res.send('Hello World!\n');
    });  
    
    app.listen(3000, function () {
      console.log('Example app listening on port 3000!');
    });
    
  3. 保存文件。

  4. 安装所需的 Express 模块:

    npm install express
  5. 启动服务器:

    node index.js

    系统会返回以下消息:
    Example app listening on port 3000

  6. 通过发送以下 HTTP 请求来测试 API。

    curl localhost:3000/v1/hello

    该 API 会返回:Hello World!

创建 OpenAPI 规范

创建用于为调用 Node.js 服务器的 API 建模的 OpenAPI 规范。

  1. 登录 apigee.com/edge
  2. 选择开发 >规格
    此时会显示规范列表。
  3. 点击 + 规范,然后在下拉菜单中选择新建规范

  4. 复制以下 YAML 内容:

    swagger: "2.0"
    info:
      version: "0.0.1"
      title: Hello World API
    host: 127.0.0.1:3000
    basePath: /v1
    schemes:
      - http
    consumes:
     - application/json
    produces:
      - application/json
    paths:
      '/hello':
        get:
          description: Returns greetings to the caller
          operationId: hello
          responses:
            "200":
              description: Success
              schema:
                $ref: "#/definitions/HelloWorldResponse"
            default:
              description: Error
              schema:
                $ref: "#/definitions/ErrorResponse"
    definitions:
      HelloWorldResponse:
        required:
          - message
        properties:
          message:
            type: string
          age:
            type: number
      ErrorResponse:
        required:
          - message
        properties:
          message:
            type: string
    
  5. 将 YAML 内容粘贴到编辑器的左侧窗格中(覆盖当前内容)。

  6. 点击保存
    系统会提示您为规范命名。

  7. 输入规范的名称,例如:simple-spec

  8. 点击继续
    系统会保存规范。

  9. 点击关闭可关闭规范并返回到规范列表。

新规范会显示在规范列表中。

后续步骤

恭喜!您已创建自己的第一个 OpenAPI 规范,以对调用目标服务器的 API 进行建模。

接下来,了解如何根据 OpenAPI 规范创建 API 代理