[Bug]: Superfluous sibling $ref when using oneOf in Schema annotation - OAS 3.1

[bostrom]

Description of the problem/issue

Using oneOf in an OAS 3.1 @Schema annotation results in an additional $ref in the root of the property.

This happens both when using two classes, and with one class, and allowing null as property value.

Expected behaviour is that $refs would only be used inside the oneOf array.

Affected Version

2.2.36

Steps to Reproduce

Allowing myProperty to be one of two classes:

Using:

    @Schema(oneOf = {SomeDto.class, OtherDto.class})

Actual outcome:

components:
  schemas:
    MyDto:
      type: object
      properties:
        myProperty:
          $ref: "#/components/schemas/SomeDto"
          oneOf:
            - $ref: "#/components/schemas/SomeDto"
            - $ref: "#/components/schemas/OtherDto"

Expected outcome:

components:
  schemas:
    MyDto:
      type: object
      properties:
        myProperty:
          oneOf:
            - $ref: "#/components/schemas/SomeDto"
            - $ref: "#/components/schemas/OtherDto"

Allowing myProperty to be a class or null:

Using:

    @Schema(oneOf = {SomeDto.class}, types = {"object", "null"})

Actual outcome:

components:
  schemas:
    MyDto:
      type: object
      properties:
        myProperty:
          type:
            - object
            - "null"
          $ref: "#/components/schemas/SomeDto"
          oneOf:
            - $ref: "#/components/schemas/SomeDto"

Expected outcome:

components:
  schemas:
    MyDto:
      type: object
      properties:
        myProperty:
          type:
            - object
            - "null"
          oneOf:
            - $ref: "#/components/schemas/SomeDto"

[djankows]

Thanks for the report @bostrom !
I tried to reproduce this on swagger-core 2.2.36 targeting OAS 3.1 with POJOs like:

    static class SomeDto {
        public String a;
    }

    static class OtherDto {
        public Integer b;
    }

    static class MyDto {
        @Schema(oneOf = { SomeDto.class, OtherDto.class })
        public Object payload;
    }

by passing the MyDto class to ModelConverters resolveAsResolvedSchema() or simply building OpenAPI and printing it with Yaml31.pretty(), but for both cases there were only $refs under oneOf.

My result:

components:
  schemas:
    MyDto:
      type: object
      properties:
        payload:
          type: object
          oneOf:
          - $ref: "#/components/schemas/SomeDto"
          - $ref: "#/components/schemas/OtherDto"
    OtherDto:
      type: object
      properties:
        b:
          type: integer
          format: int32
    SomeDto:
      type: object
      properties:
        a:
          type: string

It would help a lot if you could share a minimal repro and exact steps.

[markoka]

There is a problem with nullable properties. If the MyDto of @djankows example is changed like this:

static class MyDto {

    @Schema(types = {"object", "null"})
    public SomeDto payload;
}

Then the result is:

 MyDto:
      type: object
      properties:
        payload:
          type:
          - object
          - "null"
          $ref: "#/components/schemas/SomeDto"

Because any sibling elements of $ref are ignored, the payload property is not nullable.
For the payload property to be nullable, the result should be something like this:

  MyDto:
      type: object
      properties:
        payload:
          type:
          - object
          - "null"
          oneOf:
          - $ref: "#/components/schemas/SomeDto"

If oneOf if explicitly used in MyDto:

static class MyDto {

    @Schema(oneOf = {SomeDto.class}, types = {"object", "null"})
    public SomeDto payload;
}

Then the result has an additional $ref as @bostrom reported:

   MyDto:
      type: object
      properties:
        payload:
          type:
          - object
          - "null"
          $ref: "#/components/schemas/SomeDto"
          oneOf:
          - $ref: "#/components/schemas/SomeDto"

[bostrom]

I also had a typo in my original description:

    @Schema(oneOf = {SomeDto.class, OtherDto.class}, types = {"object", "null"})

Should be, and has now been changed to

    @Schema(oneOf = {SomeDto.class}, types = {"object", "null"})