跳到主要内容

在 Postman 中使用 Spectral

Spectral 是一个 linting 引擎，可帮助你定义自定义规则并在 JSON 和 YAML 文件上强制执行它们。Postman support Spectral v6 规则来为你的团队配置 API Governance 和 API 安全规则。

Spectral 的工作原理​

Spectral 使用一组特定规则检查 OpenAPI 文档中定义的 API 是否符合 API 设计指南。例如，使用 Spectral，你可以检查所有数据模型的所有属性是否采用驼峰式大小写，或者所有操作是否都有摘要。

Spectral 规则使用 JSON Path Plus 表达式 定位给定位置，然后使用function. 如果值不符合规则，它会返回错误。

此示例说明如何检查 API 的名称是否不包含单词“API”，而不考虑大小写（例如，“api”或“Api”）。

rules:
  api-name-doesnt-contain-api:
    given: $.info.title
    then:
      function: pattern
      functionOptions:
          notMatch: /\b(api)\b/i

首先，该规则将位于文档根 ( ) 的对象title属性作为 JSON Path Plus 表达式 的目标。在 中，named 检查属性的值是否不匹配 ( ) 在任何情况下查找单词“api”的正则表达式 ( )。info``$ $.info.title``then``function``pattern``title``functionOptions.notMatch``/\b(api)\b/i

Spectral 文档中的规则集​

Spectral 文档（通常称为规则集）具有一个rules属性，该属性可以包含一个或多个规则。

rules:
api-name-doesnt-contain-api:
# ...
api-name-length:
# ...

Spectral 使用一个键标识每个规则，该键可以是任何 JSON 兼容的字符串。

Postman 中的 Spectral 支持​

Postman support Spectral 的许多功能，但不是全部。

无论是在 Postman 中创建还是从其他来源导入，Spectral 文档都需要包含此示例中显示的属性：

rules:
  api-name-doesnt-contain-api:
    description: The API name must not contain the word API
    message: The info.title value "{{value}}" contains the forbidden word API
    severity: error
    formats:
      - oas2
      - oas3
    given:
      - $.info
    then:
      - field: title
        function: pattern
        functionOptions:
          notMatch: /\b(api)\b/i

要在 Postman 中有效，你的 Spectral 文档不能包含此处列出的属性之外的任何属性。有关规则及其说明的完整列表，请参阅 频谱规则属性 。

rules你将在可配置的 API Governance 或 API 安全页面的 自定义规则部分中找到定义的每条规则。

请记住在创建或导入自定义规则后打开它们。

Spectral 规则属性​

| 财产

描述
description规则的可选描述。如果你提供，它将显示在 API Governance 或 API 安全的可配置规则页面中。
message如果规则被触发，规则违规列表将包含message, 在 Postman 中用作规则名称。此消息旨在帮助用户解决问题。尽可能保持简短和有意义。它可以包含可选的占位符：
  • {{error}}- 返回的错误信息function。
  • {{description}}- 规则的描述。
  • {{path}}- 错误的路径（最后一个元素在property下面）。
  • {{property}}- 导致错误的属性的名称。given这在返回许多不同的属性名称或then使用多个 ) 的列表时很有用fields。
  • {{value}}- 导致错误的值。

如果message未提供，则description使用。如果description不可用，rules则使用规则的键 (in)。 | | severity | 规则检测到的问题的严重性。可能的值为error, warn（默认值）、info和hint。这些值可以按如下方式使用：

  • error- 必须修复的明显错误。
  • warn- 一个可能的错误。如果是错误，则必须修复。可以容忍对特定规则的一些偏差，例如POST没有身体。
  • info- 可以改进的东西。可以应用指南中定义的可选模式。
  • hint- 在 API 设计审查期间要讨论的内容。

| | formats | 将应用规则的文档格式列表。接受的值是：

  • oas2- 针对 OpenAPI (Swagger) 文档
  • oas3- 针对 OpenAPI 3.x 文档（3.0 和 3.1）
  • oas3_0- 针对 OpenAPI 3.0 文档
  • oas3_1- 针对 OpenAPI 3.1 文档

默认情况下，规则将针对所有版本 2 和 3.x（默认值为[oas2,oas3]）。 | | given | 必填。这可以是包含至少一个元素或单个元素的列表。每个值都是一个 JSON Path Plus 表达式 ，可以返回零个、一个或多个元素。
如果given路径找不到任何值，then控件将不会执行。 | | then | 必填。这可以是包含至少一个元素或单个元素的列表。如果给定的 JSON Path Plus 表达式 返回值，则函数将应用于所有这些值。 | | then.field | 如果路径返回的值given是一个以其中特定字段为目标的对象，则可以使用此可选名称。该值必须是名称，不能包含 JSON Path Plus expression 。
关键字@key可用于检查路径返回的对象的所有键given。 | | then.function | 必填。要使用的函数的名称。你可以在 Postman 中使用所有 Spectral 核心功能，但不支持自定义功能。有关详细信息，请参阅 Spectral 文档 。 | | then.functionOptions | 可能需要，具体取决于功能。函数的选项。你可以在 Postman 中使用所有 Spectral 核心功能，但不支持自定义功能。有关详细信息，请参阅 Spectral 文档 。 |

JSON 路径和 JSON 路径加​

JSON Path（或 JSON Path Plus）表达式旨在表示 JSON 或 YAML 文档中某些元素的路径。例如，$.info.title表示位于文档根 ( ) 的对象title的属性。info``$

最初，JSON Path 被创建为 JSON 的 XPath ，旨在表示 XML 文档中某些元素的路径。 JSON Path Plus 是 JSON Path 的扩展。它添加了更多的操作符，并使原始规范的某些行为变得明确。

构建和测试 JSON Path Plus 表达式​

你可以使用官方 JSON Path Plus 文档 来构建和测试规则的给定路径。 Syntax Through Examples ) 和 JSON Path Plus 演示 都很有用。

JSON 路径加示例​

这些示例显示了在 Postman 中创建规则所需的典型 JSON Path Plus 功能：

  • $.info.title-对象title内的属性info，位于文档的根 ( $)。
  • $.paths.*.*.responses- all 的所有操作的所有响应paths。*获取对象或数组中的所有元素。
  • $.paths.*[post,patch,put]- 所有POST，，PATCH和PUT所有操作paths。[ ]可用于过滤元素。
  • $..properties- 所有properties所有模式对象，无论它们位于何处（例如，在参数、响应或可重用组件中）。..获取路径树中的所有元素。

示例：检查属性是否存在​

下面的规则应该检查是否有 API 的描述。description但是，按照它的编写方式，当对象中不存在时，它永远不会返回违反规则的情况info。

# this approach won't work!

rules:
  info-description:
    given: $.info.description
    then:
      function: truthy

如果given路径未找到任何值，则then不会执行检查。这意味着你无法使用路径$.info.description来检查 API 描述是否在 OpenAPI 文档中定义。此验证必须使用 path 完成$.info，它将返回info对象和field 使用你要查找的字段名称（在本例中为description）设置的值。

# this approach will work

rules:
  info-description:
    given: $.info
    then:
      field: description
      function: truthy