如何修复OpenAPI校验时出现的Additional properties not allowed错误？

错误原因 #

该报错是OpenAPI语法规则不匹配导致的：Schema对象本身没有schema这个合法属性。schema字段仅允许出现在参数定义、响应体内容定义等需要嵌套声明类型的位置，你直接在属性的类型定义中新增schema字段属于不符合规范的额外字段，因此校验器会抛出非法属性的错误。

修复方案 #

你可以根据业务场景选择以下两种合规的实现方式：

方案1：通过allOf合并复用规则，保留当前phase的自定义配置

如果仅需要让PlayerStatus.phase复用SearchFilter的类型定义，同时保留当前的枚举、示例配置，使用allOf合并两个规则即可：

components:
  schemas:
    PlayerStatus:
      type: object
      properties:
        phase:
          allOf:
            - $ref: '#/components/schemas/SearchFilter'
            - x-extensible-enum: [READY, INJURED]
              example: READY

方案2：统一规则下沉到SearchFilter全局复用

如果所有用到SearchFilter的场景都需要遵循READY/INJURED的取值规则，可以直接把枚举、示例配置挪到SearchFilter定义中，所有引用的地方会自动继承规则：

components:
  schemas:
    PlayerStatus:
      type: object
      properties:
        phase:
          $ref: '#/components/schemas/SearchFilter'
    SearchFilter:
      type: string
      x-extensible-enum: [READY, INJURED]
      example: READY

两种方案都符合OpenAPI 3.0的语法规范，提交到校验器不会再报错，同时也能满足你复用SearchFilter类型的需求。

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