oneOf in Swagger schema does not work

oneOf is supported in OpenAPI version 3 (openapi: 3.0.0), but not in Swagger version 2 (swagger: '2.0').

PaymentMethod:
  oneOf:
    - $ref: '#/components/schemas/NewPaymentMethod'
    - $ref: '#/components/schemas/ExistPaymentMethod'

GitHub issue ref: https://github.com/OAI/OpenAPI-Specification/issues/333

For a list of changes in OpenAPI 3.0 compared to 2.0, see: https://blog.readme.io/an-example-filled-guide-to-swagger-3-2/


What Swagger uses is only inspired by JSON Schema. They haven't deviated too much from JSON Schema, but they leave some things out, add some things, and change some behaviors. One of the things Swagger leaves out is oneOf.

More details can be found at http://swagger.io/specification/#schemaObject