Search code examples
swaggeropenapiopenapi-generator

How can I fix Additional properties not allowed on OpenAPI?

Here's my minimal working example: there's this Open API schema that passes an 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

when I run redoc-cli bundle openapi.yaml to generate an html doc for it using ReDoc I can see: enter image description here

The thing is, I want phase's type in status to be string(SearchFilter) type as well, so I tried copy pasting its setup from 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

however when I try to insert this new spec into an online validator it says:

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

It looks like Additional properties not allowed: schema at #/properties/phase is the core error and I'm not sure how to fix it (I did manage to find questions with the same error but it looks like the title of the error is a bit misleading so it might indicate a whole lot of different errors instead).

Solution

  • schema isn't a valid keyword within a schema in OpenAPI 3.0.x

    You probably want to use an allOf to say that your schema must a satisfy two (or more) subschemas:

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