oneOf in Swagger schema does not work

yaml swagger jsonschema
fastcodejava picture fastcodejava · Apr 26, 2016 · Viewed 20.1k times · Source

I want to define PaymentMethod as below. Is oneOf supported in swagger.yaml?

PaymentMethod:
      oneOf:
        - $ref: '#/definitions/NewPaymentMethod'
        - $ref: '#/definitions/ExistPaymentMethod'

The ExistPaymentMethod will have just id, and cardNumber where NewPaymentMethod will have no id, but all other details, e.g. cardNumber, cardholderName, cardholderAddress etc.

Answer

Evan Torkos picture Evan Torkos · Jun 14, 2017

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/

Related questions

Converting Swagger specification JSON to HTML documentation

For some REST APIs written in PHP, I was asked to create Swagger documentation, and since I was not aware of any easy way of adding annotations to those existing APIs and create such a documentation, I used this editor …

Read More
How to escape colons and other special characters in a YAML string?

I have the following YAML fragment: description: | "API for bean consuming applications. Examples: painted pony, lima bean" Swagger editor interprets the colon (:) as a special character, despite the quotation marks. According to the accepted answer to this question, the colon …

Read More
How do you create a swagger schema that includes an array of varying types

I'm attempting to define a swagger schema definition for an object that contains an array of objects of varying types. Here is the json schema for a template object (and all related object types). I'm aware that swagger does not …

Read More