如何在OpenAPI中为引用属性内的字段指定常量/枚举？

你的问题核心是：通过$ref引用的复杂对象（比如SortModel），需要在父对象（TestSearchModel）中限制其内部字段的枚举值，但直接在$ref同级加enum的写法无效——这是因为OpenAPI的$ref会忽略所有同级关键字，引用会完全替换当前位置的Schema内容，所以你的枚举约束根本不会被解析。

下面是几种可行的解决方案，结合你有权修改框架SortModel的条件：

方案1：创建专用的子类Schema（推荐） #

直接基于SortModel扩展出一个针对TestSearchModel的专用Schema，在其中覆盖sortFieldName的枚举约束：

# 框架中的SortModel保持不变
SortModel:
  type: object
  properties:
    sortFieldName:
      type: string
    sortOrder:
      type: string
      enum:
        - ASC
        - DESC

# 新增针对Test场景的SortModel子类
TestSortModel:
  allOf:
    - $ref: "#/SortModel"  # 继承原SortModel的所有属性
  properties:
    sortFieldName:
      type: string
      enum:
        - ATTR_ONE
        - ATTR_TWO  # 指定Test场景允许的字段值

# 修改TestSearchModel引用专用的TestSortModel
TestSearchModel:
  type: object
  properties:
    orderBy:
      $ref: "#/TestSortModel"

这个方案的优势是复用了原框架的SortModel，同时新增的约束清晰独立，代码生成工具会自动为TestSortModel的sortFieldName生成对应枚举类，且请求中传入ATTR_THREE会触发验证错误。

方案2：内联扩展，直接覆盖字段定义 #

如果不想新增Schema，可以在TestSearchModel中直接内联orderBy的结构，复用原SortModel中sortOrder的枚举：

SortModel:
  type: object
  properties:
    sortFieldName:
      type: string
    sortOrder:
      type: string
      enum:
        - ASC
        - DESC

TestSearchModel:
  type: object
  properties:
    orderBy:
      type: object
      properties:
        sortFieldName:
          type: string
          enum:
            - ATTR_ONE
            - ATTR_TWO
        sortOrder:
          $ref: "#/SortModel/properties/sortOrder"  # 复用原sortOrder的枚举约束

这种写法避免了新增Schema，但如果SortModel结构复杂，会导致代码冗余。

验证效果 #

合法请求（会通过验证） #

{
  "orderBy": {
      "sortFieldName": "ATTR_ONE",
      "sortOrder": "ASC"
  }
}

非法请求（会触发验证报错） #

{
  "orderBy": {
      "sortFieldName": "ATTR_THREE",
      "sortOrder": "ASC"
  }
}

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