Spectral 不断发展，以满足 API 团队通过可定制的 linting 规则来强制执行质量的治理需求。我很高兴推出一个新的核心函数——or——它为您的规则集和 API 风格指南增加了更多功能。
什么是 Spectral 核心函数？
Spectral 核心函数 是 Spectral 中规则的构建块。它们封装了可重用的逻辑，例如检查属性是否存在、评估模式或比较值。您将核心函数与给定的 JSONPath 表达式和一些 functionOptions 结合使用，为您的 OpenAPI、 Arazzo 或 AsyncAPI 文档编写强大、声明性的规则。
核心函数当前列表如下：
| 函数 |
描述 |
alphabetical |
强制执行字母顺序内容，适用于简单数组，或通过传递键用于对象。 |
enumeration |
检查字段值是否存在于此组可能值中。 |
falsy |
值应为 false, "", 0, null 或 undefined。 |
length |
计算字符串或数组的长度、对象中的属性数量或数值，并定义最小值和/或最大值。 |
pattern |
使用正则表达式进行 match（匹配）或 notMatch（不匹配）。 |
casing |
文本必须匹配某种大小写，例如 camelCase（驼峰命名法）或 snake_case（蛇形命名法）。 |
schema |
使用 JSON Schema（草案 4, 6, 7, 2019-09, 或 2020-12）将 $given JSON Path 的内容视为 JSON 实例。 |
truthy |
值不应为 false, "", 0, null 或 undefined。 |
defined |
值必须已定义，这意味着它不能是 undefined。 |
undefined |
值必须是 undefined。 |
unreferencedReusableObject |
此函数识别文档中未引用的对象。 |
or **新** |
表示这些属性中需要定义一个或多个。 |
xor |
表示这些属性中需要一个，且最多只允许定义一个。 |
typedEnum |
当属性同时定义了 type 和 enum 时，枚举值必须符合类型。 |
为什么 or 函数有用？
新的 or 函数允许您断言几个指定属性中**至少一个**必须存在。当模式或对象可以通过多种方式验证时，这特别有用，并且您希望在团队或 API 之间适应这种灵活性。这有助于为高质量 API 文档提供坚实的基础，同时在去中心化决策和用例细微差别方面保持实用性。
函数签名
示例 1：模式上必须存在描述性文本
想象一下在 API 模式中强制执行文档/设计实践。您可能要求每个模式都以某种形式进行文档化，以向消费者和其他 API 设计者表达其用途（或目的）——但无需强制所有模式作者采用相同的表达机制。例如，一个人可能使用 title，另一个人使用 summary，还有一个人使用更长的 description。or 函数允许您表达这种灵活性。
上述规则集确保所有模式至少**某种程度上**有文档记录以表达其目的，而无需强制特定的文档风格。
示例 2：确保字符串模式的有用提示
在另一个常见情况下，您可能希望确保每个 type: string 模式都通过 format、example 或 pattern 包含一个对开发人员有用的提示或约束。同样，这里允许多个，但至少应存在一个：
社区贡献
衷心感谢 Clyde Cutting 💛 添加此功能。他在金融数据交换 (Financial Data Exchange) 及其用于开放银行 API 的 FDX API 风格指南中的出色工作中需要此功能。像这样的社区 贡献 有助于 Spectral 发展成为一个更强大、更实用的工具。
立即试用
更新到最新版本的 Spectral，并在您自己的规则集中试用 or 函数。无论您是强制执行模式文档、命名约定还是结构灵活性，or 都为您提供了额外的声明性表达方式。