第 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 开源项目 的"light"版本，所以在 API Designer 界面中显示 "Apicurio"。

2. 单击 New API。此时会打开一个新的 API 页面。

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

   注意

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

3. 更改 API 名称：

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

4. （可选）：

   • 提供版本号和描述。
   • 添加联系信息（名称、电子邮件地址和 URL）。
   • 选择一个许可证。
   • 定义标签。
   • 定义一个或多个服务器。
   • 配置安全方案。
   • 指定安全要求。

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

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

   • 任务的路径： /todo

   • 按 ID 为特定任务的路径： /todo/{id}

     

     View larger image

     

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

   对于示例 id 参数：

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

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

   2. 点 Create。
   3. 作为描述，键入： 要查找的任务 ID。

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

      

      View larger image

      

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

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

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

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

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

      Copy to Clipboard Toggle word wrap
   4. 另外，您可以选择使用数据类型创建 REST 资源。

   5. 点击 Save。如果您提供了示例，API Designer 从示例生成 schema：

      

      View larger image

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

9. 对于 Task Management API 示例，使用类型为 string 的属性创建一个名为 Task 的另一个数据类型。

   

   View larger image

   

10. 对于每个路径，定义操作（GET、PUT、POST、DE、OPTIONS、HEAD 或 PATCH）。

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

    Expand

    表 3.1. 任务管理 API 操作

    路径	操作	描述	申请正文	响应
    /todo	POST	创建新任务。	media Type: application/json Data Type: Task	Status Code: 201 Description: Task created response Body: Media Type: application/json Data Type: Todo
    /todo	GET	获取所有任务。	Not applicable	Status Code： 200 Description : 任务列表
    /todo/{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.
    /todo/{id}	PUT	按 ID 更新任务。	request Body type: Task	Status Code: 200 Description: Completed Status Code： 400 Description: Task not updated
    /todo/{id}	删除	按 ID 删除任务。	Not applicable	Status Code: 200 Description: Task delete Status Code： 400 Description: Task not delete

    Show more
11. 解决所有问题，如 解决 API Designer 中的验证问题中所述。

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

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