It’s a common mistake when working on specifications, reading newer docs and mixing and matching capabilities. This rule checks for those mistakes.
We would recommend against using ‘oneOf’ in general. It might make things easier to build complex models, but it does not translate well when tools like code generators try and create polymorphic structures, and the target language doesn’t support inheritance; (like golang).
Think of it this way: As a consumer of this API, ‘oneOf’ means my application is getting a number of different types of objects back. My application would have to build logic to cater to each different variation of response combinations.
It’s not a great DX.
Make your API definitions explicit in nature.
Why did this violation appear?
swagger: 2.0 paths: /mystery: post: parameters: - in: body name: whatCouldItBe schema: oneOf: - $ref: "#/shared-components/schemas/Meat" - $ref: "#/shared-components/schemas/Cake" ...
openapi: 3.1 /pets: post: requestBody: content: application/json: schema: oneOf: - $ref: "#/shared-components/schemas/Meat" - $ref: "#/shared-components/schemas/Cake"
How do I fix this violation?
Don’t use oneOf with a Swagger/OpenAPI 2 spec. It’s not compatible.
The rule is equivalent to oas2-oneOf