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

Question

这是我的最小工作示例：有这个 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:[=21= 复制粘贴其设置]

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 是核心错误，我不确定如何修复它（我确实设法找到了具有相同错误的问题，但看起来错误的标题有点具有误导性，因此它可能会指示很多不同的错误）。

Answer 1

schema 不是 OpenAPI 3 中 schema 中的有效关键字。0.x

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

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

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

How can I fix Additional properties not allowed on OpenAPI?

swagger

openapi

openapi-generator