如何用Spectral规则验证OpenAPI正则？自定义规则校验问题排查

规则要求 #

• URI路径必须为kebab-case格式（小写单词用连字符-连接），示例：/payments/pending、/payments/pending-payments
• 路径参数（如{petId}）和查询字符串参数必须为lowerCamelCase格式，示例：{paymentId}、paymentType=xxx

原规则问题点 #

1. paths-kebab-case的正则包含多余空格，且单层级路径（如/pets）的匹配逻辑有漏洞，导致误判
2. path-parameter-must-lower-camel-case的given路径错误，直接匹配整个路径字符串而非目标路径参数，正常路径也被标记为错误

修正后的完整规则集 #

paths-kebab-case:
  description: Paths should be kebab-case (lowercase words separated by hyphens)
  message: "{{property}} must be kebab-case (lowercase with hyphens for separators)"
  severity: error
  given: $.paths[*]~
  then:
    function: pattern
    functionOptions:
      match: "^(/([a-z0-9]+(-[a-z0-9]+)*|{[a-z][a-zA-Z0-9]*}))+$"

path-parameters-lower-camel-case:
  description: Path parameters must use lowerCamelCase
  message: "Path parameter '{{value}}' must be lowerCamelCase (starts with lowercase, subsequent words capitalized)"
  severity: error
  given: "$.paths.*.parameters[?(@.in === 'path')].name"
  then:
    function: pattern
    functionOptions:
      match: "^[a-z][a-zA-Z0-9]*$"

query-parameters-lower-camel-case:
  description: Query parameters must use lowerCamelCase
  message: "Query parameter '{{value}}' must be lowerCamelCase (starts with lowercase, subsequent words capitalized)"
  severity: error
  given: "$.paths.*.parameters[?(@.in === 'query')].name"
  then:
    function: pattern
    functionOptions:
      match: "^[a-z][a-zA-Z0-9]*$"

修正细节说明 #

1. paths-kebab-case规则 #

• 移除正则内多余空格，匹配逻辑更严谨
• 正则结构分解：
  • [a-z0-9]+(-[a-z0-9]+)*：匹配合法的kebab-case路径段，允许小写字母、数字，连字符分隔单词
  • {[a-z][a-zA-Z0-9]*}：匹配符合lowerCamelCase的路径参数，确保参数名以小写开头，后续可包含大小写字母或数字
  • 整体^(/(xxx|yyy))+$确保整个路径由合法段组成，支持单层级或多层级路径

2. 路径参数校验 #

直接通过JSONPath$.paths.*.parameters[?(@.in === 'path')].name定位到所有路径参数的名称字段，用正则^[a-z][a-zA-Z0-9]*$精准校验，避免误判正常路径

3. 查询参数校验 #

新增规则覆盖查询参数，同样通过JSONPath定位到in: query的参数名称，用相同的lowerCamelCase正则校验，满足规则要求

测试验证 #

用提供的Swagger Petstore示例测试：

• /pets：符合kebab-case规则，无错误
• /pets/{petId}：路径为kebab-case，petId符合lowerCamelCase，无错误
• 若路径写成/Pets或参数名写成PetID，会触发对应的错误提示

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