如何修复 OpenAPI 上不允许的其他属性？

如何解决如何修复 OpenAPI 上不允许的其他属性？

这是我的最小工作示例：有一个传递 online validator 的 Open API 架构：

---
openapi: 3.0.0
info:
  title: Players API
  version: 0.0.1

paths:
  /players:
    get:
      operationId: getPlayer
      parameters:
        - name: phase
          in: query
          schema:
            $ref: '#/components/schemas/SearchFilter'
          example: READY
      responses:
        '200':
          description: Player
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
components:
  schemas:
    Player:
      type: object
      properties:
        status:
          $ref: '#/components/schemas/PlayerStatus'
    PlayerStatus:
      type: object
      properties:
        phase:
          type: string
          x-extensible-enum: [READY,INJURED]
          example: READY
    SearchFilter:
      type: string

当我运行 redoc-cli bundle openapi.yaml 以使用 ReDoc 为其生成 html 文档时，我可以看到：

问题是，我希望 phase 的状态类型也为 string(SearchFilter) 类型，因此我尝试从 properties 复制粘贴其设置：

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

但是，当我尝试将这个新规范插入在线验证器时，它说：

Swagger schema validation Failed. 
  Data does not match any schemas from 'oneOf' at #/components/schemas/PlayerStatus
    Data does not match any schemas from 'oneOf' at #/components/schemas/PlayerStatus/properties/phase
      Additional properties not allowed: schema at #/properties/phase
      Missing required property: $ref at #/properties/phase
    Missing required property: $ref at #/components/schemas/PlayerStatus
  Data does not match any schemas from 'oneOf' at #/components/schemas/Player
    Data does not match any schemas from 'oneOf' at #/components/schemas/Player/properties/status
      Data does not match any schemas from 'oneOf' at #/properties/status/properties/phase
        Additional properties not allowed: schema at #/properties/phase
        Missing required property: $ref at #/properties/phase
      Missing required property: $ref at #/properties/status
    Missing required property: $ref at #/components/schemas/Player

看起来 Additional properties not allowed: schema at #/properties/phase 是核心错误，我不知道如何修复它（我确实设法找到了具有相同错误的问题，但看起来错误的标题有点误导，所以相反，它可能表示很多不同的错误）。

解决方法

schema 不是 OpenAPI 3.0.x 中 schema 中的有效关键字

您可能想使用 allOf 表示您的架构必须满足两个（或更多）子架构：

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