如何修复 OpenAPI 上不允许的附加属性？答案

【问题标题】：How can I fix Additional properties not allowed on OpenAPI?如何修复 OpenAPI 上不允许的附加属性？
【发布时间】：2021-05-24 23:22:57
【问题描述】：

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

---
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 是核心错误，我不确定如何修复它（我确实设法找到了具有相同错误的问题，但看起来错误的标题有点误导，所以它可能而是指出一大堆不同的错误）。

【问题讨论】：

标签： swagger openapi openapi-generator

【解决方案1】：

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'

【讨论】：

Schema 现在通过验证器，谢谢！也就是说，我遇到了另一个与渲染相关的问题：imgur.com/a/ItqS0jz，你有什么想法吗？