Using $refs in Open Api 3.0.x yaml format, Swagger

Question

I am trying to document an api on swagger (Open api 3.0.x) and I find a problems using $refs.

As written here, it's working as intended, BUT debugger shows an error my request body definition (it lacks content, application/json, schema)

What is the correct way to do this?

/foobarbaz:
    post:   
     requestBody:
        description: lorem ipsum
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/requestBodies/foo'
                - $ref: '#/components/requestBodies/bar'
                - $ref: '#/components/requestBodies/baz'
        examples:
              foo:
                $ref: '#/components/examples/foo'
              bar:
                $ref: '#/components/examples/bar'
              baz:
                $ref: '#/components/examples/baz'

components:
  requestBodies: 
    foo: <-- here it highlights (Missing property "$ref".)
    schema
     type: object
      properties:
        foo:
          type: string
        bar:
          type: string
    bar: <-- here it highlights (Missing property "$ref".)
    schema
     type: object
      properties:
        foo:
          type: string
        bar:
          type: string
    baz: <-- here it highlights (Missing property "$ref".)
    schema
     type: object
      properties:
        foo:
          type: string
        bar:
          type: string

  examples:
    foo:
      value:
        foo: 'bar'
        bar: '20'
    bar:
      value:
        foo: 'bar'
        bar: '20'
    baz:
      value:
        foo: 'bar'
        bar: '20'

Helen Helen · Accepted Answer · 2021-04-08T14:05:32

oneOf can only $ref schemas, not requestBody components. Here's the correct version:

  /foobarbaz:
    post:   
     requestBody:
        description: lorem ipsum
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/foo'  # <--- $refs point to schemas, not requestBodies
                - $ref: '#/components/schemas/bar'
                - $ref: '#/components/schemas/baz'
        examples:
          ...

components:
  schemas:   # <--- Put the schemas in the "schemas" section rather than "requestBodies"
    foo:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: string
    bar:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: string
    baz:
      type: object
      properties:
        foo:
          type: string
        bar:
          type: string

Using $refs in Open Api 3.0.x yaml format, Swagger

1 Answers