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

流程

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

   如果您在 OpenShift 中使用 Fuse：

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

   2. 对于 OpenShift 4.x，选择 Topology，然后单击 apicurito-service-ui 图标上的 URL 链接。

      对于 OpenShift 3.11，从应用程序列表中点 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 页面。

   默认情况下，API Designer 使用 OpenAPI 3 规格。如果要使用 OpenAPI 2 规格，点 New API 按钮旁的箭头，然后选择 OpenAPI 2。

   注意

   如果基于 OpenAPI 2 规格打开 API，您可以使用 API Designer 的 Convert 到 OpenAPI 3 选项，来转换 API 以符合 OpenAPI 3 规格。

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 示例，请按照下表所述定义操作：

    表 3.1. 任务管理 API 操作

    路径	操作	描述	请求正文	响应
    /todo	POST	创建新任务。	media Type: application/json Data Type: Task	Status Code: 201 Description: Task created 响应正文： Media Type: application/json Data Type: Todo
    /todo	GET	获取所有任务。	Not applicable	Status Code: 200 Description : 任务列表
    /cleanup/{id}	GET	按 ID 获取任务。	Not applicable	Status Code: 200 Description: Task found for ID Response Body: Media Type: application/json Data type: Task Status Code: 404 Description: No task with provided identifier found.
    /cleanup/{id}	PUT	按 ID 更新任务。	request Body type: Task	Status Code: 200 Description: Completed Status Code: 400 Description: Task not updated
    /cleanup/{id}	DELETE	按 ID 删除任务。	Not applicable	Status Code: 200 Description: Task deleted Status Code: 400 Description: Task not deleted

11. 解决任何问题，如 API Designer 中的解决验证问题 中所述。

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

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