Arazzo：OpenAPI 的工作流扩展规范

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

描述 API 工作流

在实际应用中，API 通常不是单一操作。例如：

用户可能先通过 OAuth 登录，然后利用响应中的属性从其他端点获取数据；
或者需要先创建资源，再继续获取其他数据。

传统 API 文档通常无法直观展示这些复杂流程，而 Arazzo 提供了声明式方式，将操作与输入、输出结合，引用 OpenAPI 文档，实现清晰工作流展示。

Arazzo 文件示例

以下是基于火车旅行 API 的示例，展示如何使用 Arazzo 定义工作流：

查找两个车站
查询运行的火车
使用数据完成订票操作

通过这个示例，可直观理解 Arazzo 的工作原理。

Arazzo 语法

Arazzo 语法与 OpenAPI 类似，主要组成部分如下：

信息对象

定义与工作流相关的元数据。

源代码描述对象

指定使用的 API 描述格式（如 “openapi” 或 “arazzo”），并指向 API 文档的 URL，可为相对路径或完整 URL。

工作流

workflowId：工作流唯一标识
摘要与描述：简短说明与详细描述
输入：标准 JSON Schema 定义参数，或引用 components.inputs

步骤对象

名称：每个步骤唯一标识
operationId：对应 OpenAPI 文档中的操作
parameters：包括 path、query、header 和 cookie 等类型，值可硬编码或引用工作流输入

成功标准

判断操作是否成功，最基本方式是检查 HTTP 状态码 200 或 201。
高级方式可使用运行时表达式语法：

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

如果响应为 JSON 或 XML，可使用：

JSONPath
XPath

例如：

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

输出

从响应提取值，用于后续步骤：

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

提示与最佳实践

扩展其他工作流

可通过调用另一个工作流的 workflowId 来复用操作组。

向 OpenAPI 添加 operationId

在 OpenAPI 文档中定义 operationId 有助于生成清晰文档和 SDK，也简化 Arazzo 中引用操作。

\$ref 与引用

Arazzo 使用 reference 关键字，提供比 OpenAPI $ref 更灵活的引用机制。

工具支持

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

总结

Arazzo 扩展了 OpenAPI 的能力，可声明式定义复杂 API 工作流的输入、输出和步骤，同时支持条件判断和引用机制。无论用于测试、文档或 AI 应用，Arazzo 为推动 API 生态发展提供了新可能性。

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