如何在Spectral中强制请求响应参数使用snake_case？

核心问题分析 #

1. 路径覆盖不全：原配置的given仅匹配schemas下直接的properties，没覆盖嵌套结构（比如数组items内的对象属性）、请求/响应中的Schema。
2. 正则表达式错误：原正则^[a-z_\/{}]*$允许空字符串、多余符号，不符合标准snake_case（小写字母+下划线，无特殊字符，且不能以下划线开头/结尾）。

修正后的完整配置 #

extends: ["spectral:oas", "spectral:asyncapi"]
rules:
  snake-case-for-keys:
    description: 所有属性名必须使用snake_case命名规范
    severity: error
    # 覆盖所有可能出现属性名的位置：
    # 1. components.schemas下的所有对象属性（含嵌套）
    # 2. paths中请求/响应的schema内的对象属性（含嵌套）
    given: |
      $..properties.*,
      $..items.properties.*,
      $..additionalProperties.properties.*,
      $..requestBody.content.*.schema..properties.*,
      $..responses.*.content.*.schema..properties.*
    then:
      field: '@key'
      function: pattern
      functionOptions:
        # 标准snake_case正则：小写字母开头，后续可跟下划线+小写字母，禁止下划线开头/结尾
        match: '^[a-z]+(?:_[a-z]+)*$'

配置说明 #

• given路径：使用JSONPath的递归匹配（..）覆盖所有嵌套层级的properties，同时包含请求体、响应体中的Schema，确保所有接口相关的属性名都被检查。
• 正则表达式：^[a-z]+(?:_[a-z]+)*$确保：
  • 必须以小写字母开头
  • 只能包含小写字母和下划线
  • 不能以下划线结尾，也不能出现连续下划线
• 覆盖范围：包含了components中的Schema、接口请求体、响应体，以及嵌套的数组items、additionalProperties中的对象属性。

验证示例 #

针对你提供的Schema：

components:
  schemas:
    SomeSchema:
      type: array
      items:
        type: object
        properties:
          someProperty: # 会触发错误，不符合snake_case
            type: string

修正后someProperty改为some_property即可通过检查。

内容的提问来源于stack exchange，提问作者Antonio Gamiz Delgado