使用Stoplight Spectral校验OpenAPI YAML时如何解决指定错误

常见排查步骤 #

• 检查规则文件语法：确保你的.spectral.yaml或.spectral.json没有YAML/JSON语法错误，比如遗漏逗号、引号不闭合、缩进错误。
• 确认规则文件路径：执行校验命令时，指定的规则集路径是否正确。比如使用spectral lint openapi.yaml -r ./my-ruleset.yaml，要确保./my-ruleset.yaml确实存在于当前工作目录。
• 校验规则集结构：规则集必须符合Spectral规范，顶层要有rules字段，每个规则需包含description、severity和given/then等必要属性。示例正确规则片段：

rules:
  no-unused-components:
    description: Components should be referenced somewhere in the API
    severity: error
    given: $.components
    then:
      field: '#/components/*'
      function: schema
      functionOptions:
        schema:
          minProperties: 1

• 检查内置规则引用：如果规则集继承了官方规则集（比如extends: ["spectral:oas"]），确保规则集名称拼写无误，或已正确安装相关依赖。
• 简化测试：先使用默认规则集测试，执行spectral lint openapi.yaml不指定自定义规则，看是否能正常运行。如果正常，再逐步添加自定义规则排查问题。

内容的提问来源于stack exchange，提问作者Gideon