第 3 章 使用 API Designer 设计和开发 API 定义
您可以使用 API Designer 设计和开发符合 OpenAPI 3(或 2)规范的 REST API 定义。
先决条件
- 您创建了 OpenShift 项目。
- 您已将 API Designer 服务添加到 OpenShift 项目。
3.1. 在 API Designer 中创建 REST API 定义 复制链接链接已复制到粘贴板!
以下步骤描述了如何创建 REST API 定义。
- 您可以从 OpenShift 上的 Fuse Online 或 Fuse 访问 API Designer 用户界面。
- 对于 OpenShift 上的 Fuse,API Designer 是无状态的,这意味着它不会在 OpenShift 会话之间保存您的工作。您需要在会话之间将 API 保存到本地文件系统。
关于示例
Task Management API 示例模拟一个简单的 API,销售顾问可能会用来跟踪在与客户联系交互时需要执行的任务。"to-do"任务示例可以是"为新联系人创建帐户"或"放置现有联系顺序"。要实现任务管理 API 示例,您需要创建两个路径 - 一个用于任务,一个用于特定任务。然后,您可以定义创建任务的操作,检索所有任务或特定任务,更新任务,以及删除任务。
先决条件
-
您知道您要创建的 API 的端点。对于任务管理 API 示例,有两个端点:
/todo
和/todo/{id}
。 - 对于 OpenShift 上的 Fuse,您可以创建一个 OpenShift 项目,并将 API Designer 服务添加到 OpenShift 项目中。
流程
如果您使用 Fuse Online,请跳至第 2 步。
如果要在 OpenShift 中使用 Fuse:
- 登录您的 OpenShift Web 控制台,然后打开包含 API Designer 的项目。
对于 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"。
单击 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 规格。
更改 API 名称:
-
将光标悬停在名称上,然后点显示的编辑图标(
)。
- 编辑名称。例如,键入 Task API。
- 单击复选标记图标以确认名称更改。
-
将光标悬停在名称上,然后点显示的编辑图标(
(可选):
- 提供版本号和描述。
- 添加联系信息(名称、电子邮件地址和 URL)。
- 选择一个许可证。
- 定义标签。
- 定义一个或多个服务器。
- 配置安全方案。
- 指定安全要求。
定义指向 API 各个端点的相对路径。字段名称必须以斜杠(/)开头。
对于 Task Management API 示例,创建两个路径:
-
任务的路径:
/todo
按 ID 为特定任务的路径:
/todo/{id}
-
任务的路径:
指定任何路径参数的类型。
对于示例
id
参数:在 Paths 列表中,单击
/todo/{id}
。id 参数会出现在 PATH PARAMETERS 部分。
- 点 Create。
- 作为描述,键入: 要查找的任务 ID。
对于类型,选择 32 位整数。
在 Data Types 部分中,为 API 定义可重复使用的类型。
- 点 Add a data type。
- 在 Add Data Type 对话框中输入名称。对于 Task Management API 示例,键入 Todo。
另外,您还可以提供从哪个 API Designer 创建数据类型 schema 的示例。然后,您可以编辑生成的 schema。
对于 Task Management API 示例,从以下 JSON 示例开始:
{ "id": 1, "task": "my task", "completed": false }
{ "id": 1, "task": "my task", "completed": false }
Copy to Clipboard Copied! Toggle word wrap Toggle overflow - 另外,您可以选择使用数据类型创建 REST 资源。
点击 Save。如果您提供了示例,API Designer 从示例生成 schema:
- 另外,您可以添加编辑模式属性并添加新属性。
对于 Task Management API 示例,使用类型为 string 的属性创建一个名为 Task 的另一个数据类型。
对于每个路径,定义操作(GET、PUT、POST、DE、OPTIONS、HEAD 或 PATCH)。
对于 Task Management API 示例,按照下表所示定义操作:
Expand 表 3.1. 任务管理 API 操作 路径 操作 描述 申请正文 响应 /todo
POST
创建新任务。
media Type:
application/json
Data Type: TaskStatus 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
- 解决所有问题,如 解决 API Designer 中的验证问题中所述。
对于 OpenShift 上的 Fuse,请点击 Save As 来保存 API 规格,然后选择 JSON 或 YAML 格式。
JSON 或 YAML 文件下载到您的本地下载文件夹。默认文件名是
openapi-spec
具有适当文件扩展名。
其他资源
- 有关 OpenAPI 规格的详情,请转至 :https://github.com/OAI/OpenAPI-Specification