Arazzo：OpenAPI 的工作流扩展规范

Arazzo 是 OpenAPI 倡议推出的一项新规范，旨在描述和记录 API 中涉及多个操作（或称端点）的复杂工作流。Arazzo 的命名灵感来源于意大利语中的“挂毯”，象征着将多个操作编织成一个整体的能力。本文将详细介绍 Arazzo 的功能、语法以及其在 API 工作流中的应用。

描述 API 工作流

在实际应用中，API 通常并非单一的请求操作。例如，用户可能需要通过 OAuth 登录，然后利用响应中的某个属性从其他端点获取数据；或者需要先创建某些资源，才能继续获取其他数据。然而，API 文档通常无法直接清晰地展示这些复杂的操作流程。虽然参考文档和教程可以提供帮助，但它们往往需要手动生成，容易出现人为错误。

Arazzo 提供了一种声明式的方式来定义这些工作流。通过将操作与输入、输出相结合，并引用 OpenAPI 的相关部分，Arazzo 能够清晰地展示 API 的各个组成部分如何协同工作。

Arazzo 文件示例

以下是一个基于火车旅行 API 的示例，展示了如何使用 Arazzo 定义一个工作流。该工作流包括查找两个车站、找到在它们之间运行的火车，以及使用这些数据完成订票操作。通过这个示例，我们可以直观地了解 Arazzo 的工作原理。

Arazzo 语法

Arazzo 的语法设计与 OpenAPI 类似，以下是其主要组成部分：

信息对象

首先，需要定义一个“信息”对象，用于包含与工作流目的相关的元数据。

源代码描述对象

接下来是“源描述”部分。OpenAPI 是一种 API 描述格式，存储为 API 描述文档。在此部分，可以指定所使用的 API 描述格式类型（如 “openapi” 或 “arazzo”），并指向具体的 API 描述文档。文档的 URL 可以是相对路径，也可以是完整的 URL，例如 https://...。

工作流

在 Arazzo 中，工作流是核心部分。与 OpenAPI 的路径和操作类似，Arazzo 定义了工作流的 workflowId，用于唯一标识工作流。此外，还可以为工作流提供简短的“摘要”和详细的“描述”。工作流的输入通常以标准 JSON 模式定义，描述了需要提供给工作流的参数。这些输入可以直接定义，也可以引用 components.inputs。

步骤对象

Arazzo 的主要部分是“步骤”。每个步骤都有一个唯一的名称，例如“查找源站”，并可以在文档的其他部分引用。步骤中的 operationId 对应 OpenAPI 文档中的某个操作，而 parameters 则与该操作的参数相匹配。

参数的定义类似于 OpenAPI，包括 path、query、header 和 cookie 等类型。参数的值可以是硬编码的，也可以引用前面定义的工作流输入。

成功标准

每个步骤可以定义“成功标准”，用于判断操作是否成功。最基本的成功标准是检查 HTTP 状态码是否为 200 或 201。此外，还可以使用运行时表达式语法进行更复杂的条件判断。例如：

条件：$statusCode == 200 || $statusCode == 201```

如果响应是 JSON 或 XML 格式，还可以使用 JSONPath 或 XPath 进行更高级的条件判断。例如：

```plaintext
上下文：$response.body
条件：$[?count(@.data) > 0]
类型：jsonpath

输出

步骤的输出可以从响应中提取值，并提供给后续步骤。例如：

输出：station_id: $outputs.data[0].id

通过将步骤的输入和输出连接起来，可以构建复杂的工作流，并为不同的用例生成多个工作流文档。

提示与最佳实践

扩展其他工作流

如果某些操作或操作组需要重复使用，可以通过定义一个运行工作流的步骤来实现复用。在这种情况下，可以引用另一个工作流的 workflowId，而无需重新定义参数。

向 OpenAPI 添加操作 ID

在 OpenAPI 文档中使用 operationId 是一种推荐的做法。它不仅可以生成更干净的文档和 SDK，还能在 Arazzo 中简化操作的引用。如果缺少 operationId，则需要使用更复杂的 operationPath 语法，这可能导致路径变化时出现问题。

$ref 与引用

Arazzo 引入了一种新的引用机制，即 reference 关键字，与 OpenAPI 中的 $ref 不同。这种基于表达式的引用机制可以在多个部分使用，提供了更大的灵活性。

工具支持

目前，Arazzo 的工具支持正在逐步完善。随着更多工具供应商的加入，Arazzo 有望成为描述 API 工作流的标准规范，为 API 文档和测试提供更强大的支持。

总结

Arazzo 作为 OpenAPI 的扩展规范，为描述复杂的 API 工作流提供了强大的工具。通过声明式的语法，Arazzo 能够清晰地定义操作的输入、输出和步骤，并支持复杂的条件判断和引用机制。无论是测试、文档还是 AI 应用，Arazzo 都为推动 API 生态系统的发展提供了新的可能性。

原文链接: https://bump.sh/blog/arazzo-describe-api-workflows-extension-openapi