Spectral自定义规则验证OpenAPI示例的注意事项

问题背景

在使用Spectral验证OpenAPI规范时，开发者经常需要确保API文档中包含足够的示例数据。示例数据对于API消费者理解请求和响应格式至关重要。然而，在自定义规则验证示例时，可能会遇到一些意料之外的行为。

自定义规则分析

最初，开发者尝试使用以下规则来验证所有操作是否包含示例：

operation-must-have-examples:
  description: All object types must include at least one example
  message: Return or request type is missing an example in the schema.
  severity: warn
  given: $.paths.*.*.*.content[application/json]
  then:
    field: schema.example
    function: truthy

这条规则看起来合理，它检查所有路径操作中application/json内容类型的schema.example是否存在。然而，在实际应用中，开发者发现对于某些响应，即使移除了示例，规则仍然不会报错。

问题根源

经过深入分析，发现问题出在JSON路径的选择上。OpenAPI规范中，请求和响应的结构层级是不同的：

1. 请求参数位于：$.paths.*.*.*.content[application/json]
2. 响应内容位于：$.paths.*.*.*.*.content[application/json]（多一层）

原始规则只匹配了请求参数的路径，因此无法正确验证响应中的示例。

解决方案

正确的做法是为请求和响应分别创建独立的验证规则：

operation-must-have-examples-requests:
  description: All object types must include at least one example
  message: Request type is missing an example in the schema.
  severity: warn
  given: $.paths.*.*.*.content[application/json]
  then:
    field: schema.example
    function: truthy

operation-must-have-examples-responses:
  description: All object types must include at least one example
  message: Response type is missing an example in the schema.
  severity: warn
  given: $.paths.*.*.*.*.content[application/json]
  then:
    field: schema.example
    function: truthy

最佳实践建议

1. 理解OpenAPI结构：在编写自定义规则前，充分理解OpenAPI规范的结构层次非常重要。

2. 分而治之：对于不同层级的验证需求，建议创建独立的规则，而不是试图用一个规则覆盖所有情况。

3. 测试验证：修改规则后，应该测试各种边界情况，确保规则按预期工作。

4. 明确错误信息：为不同规则提供明确的错误信息，帮助开发者快速定位问题。

5. 考虑使用预置规则：Spectral提供了一些内置规则，如oas3-api-servers等，可以先检查是否有现成规则可用。

通过这种方式，可以确保API文档中的请求和响应都包含必要的示例数据，提高API文档的质量和可用性。