Swagger V2.0 复用Enum类型时如何为引用属性设置默认值

Swagger 2.0 遵循 JSON Schema 核心规则：当节点存在 $ref 属性时，该节点的所有同级属性都会被解析器忽略。$ref 的作用是将当前节点整体替换为引用目标的内容，因此你之前写在 $ref 同级的 default 字段根本不会生效。你尝试设置默认值为引用路径的写法也不符合规范，default 必须填写枚举的实际值。

有两种可实现枚举复用的配置方式，按需选择即可：

方案1：默认值全局统一（所有引用该枚举的位置共用默认值） #

直接将default字段写在枚举定义内部，所有引用该枚举的节点会自动继承默认值：

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      $ref: '#/definitions/StatusEnum'

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']
    default: 'UNKNOWN' # 把默认值定义在枚举内部

方案2：默认值按需配置（不同引用位置可设置不同默认值） #

使用allOf关键字包裹枚举引用，default字段写在allOf同级，不会被解析器忽略：

"/uri/path":
  ...
  parameters:
    - in: body
      ...
      schema:
        $ref: '#/definitions/StatusObject'

definitions:
  StatusObject:
    status:
      allOf:
        - $ref: '#/definitions/StatusEnum'
      default: 'UNKNOWN' # 当前引用位置的专属默认值

  StatusEnum:
    type: string
    enum: ['ALPHA', 'BRAVO', 'UNKNOWN']

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