第 2 章 使用 API Designer 设计和开发 API 定义

流程

1. 如果您使用 Fuse Online，请跳至第 2 步。

   如果您在 OpenShift 中使用 Fuse：

   1. 登录您的 OpenShift Web 控制台，然后打开包含 API Designer 的项目。

   2. 在应用程序列表中，点 API Designer 的 URL，例如 https://apidesigner-myproject.192.168.64.43.nip.io

      为 API Designer 打开一个新的浏览器窗口或标签页。

      注意

      因为 API Designer 是 Apicurio Studio 开源项目的 "亮点"版本，所以 "Apicurio" 显示在 API Designer 界面中。

2. 单击 New API。这会打开新的 API 页面。

3. 更改 API 名称：

   1. 将光标悬停在名称上，然后点显示的编辑图标( )。
   2. 编辑名称。例如，键入 Task API。
   3. 确认名称更改。

4. （可选）：

   • 添加您的联系信息（姓名、电子邮件地址和 URL）。
   • 选择许可证。
   • 定义标签。
   • 定义安全方案。
   • 指定安全要求。

5. 定义 API 的每个端点的相对路径。字段名称必须以斜杠(/)开头。

   对于 Task Management API 示例，创建两个路径：

   • 任务的路径： /setuptools

   • 一个特定任务的路径，按 ID: / covers/{id}

     

6. 指定任何路径参数的类型。

   对于示例 id 参数：

   1. 在 Paths 列表中，单击 /cleanup/{id}。

      id 参数会出现在 PATH PARAMETERS 部分中。

   2. 点 Create。
   3. 对于描述，type： 要查找的任务 ID。

   4. 对于类型，将 整数 选为 32 位整数。

      

7. 在 Data Types 部分中，为 API 定义可重复使用的类型。

   1. 单击 Add a data type。
   2. 在 Add Data Type 对话框中输入名称。对于 Task Management API 示例，键入 Todo。

   3. 另外，您可以提供一个示例，API Designer 创建数据类型的 schema。然后，您可以编辑生成的模式。

      对于 Task Management API 示例，从以下 JSON 示例开始：

      {
          "id": 1,
          "task": "my task",
          "completed": false
      }

   4. 另外，您可以选择使用数据类型创建 REST 资源。

   5. 点 Save。如果您提供了示例，API Designer 从示例中生成一个模式：

      
8. 另外，您可以添加编辑模式属性并添加新模式属性。

9. 对于 Task Management API 示例，创建另一个名为 Task 的数据类型，其名为 string 的任务。

   

10. 对于每个路径，定义操作(GET、PUT、POST、DELETE、OPTIONS、HEAD 或 PATCH)。

    对于 Task Management API 示例，请按照下表所述定义操作：

    表 2.1. 任务管理 API 操作

    路径	操作	描述	Request（请求）	响应
    /todo	POST	创建新任务。	request Body type: Task	状态代码： 201 Description: Task created 响应正文： Todo 类型
    /todo	GET	获取所有任务。	Not applicable	状态代码： 200 描述： 任务已删除 状态代码： 400 Description: Task not deleted
    /todo/{id}	GET	按 ID 获取任务。	Not applicable	状态代码： 200 描述 ： 为 ID 找到的任务 响应正文： Todo 类型
    /todo/{id}	UPDATE （更新）	按 ID 更新任务。	request Body type: Task	状态代码： 200 描述： 完成 状态代码： 400 Description: Task not updated
    /todo/{id}	DELETE	按 ID 删除任务。	Not applicable	状态代码： 200 描述： 任务已删除 状态代码： 400 Description: Task not deleted

11. 解决任何问题，如 第 2.2 节 “解决 API 设计程序中的问题” 所述。

12. 对于 OpenShift 上的 Fuse，点 Save As，然后选择 JSON 或 YAML 格式来保存您的 API 规格。

    JSON 或 YAML 文件下载到您的本地下载文件夹中。默认文件名为 openapi-spec，带有适当的文件扩展名。