Implement detection rules for adding/removing discriminated types

[macisamuele]

Add a new discriminated type (model) used in responses

Rationale

Polymorphism, done using the discriminator keyword, allows returning different objects that are united by the fact that a string property is required. The content of the property represent the specific type of the object. Adding a new discriminated type, that will be used in responses, is backward incompatible as a new object type could be returned to clients that are operating with "old" Swagger spec and they would not be able to properly handle the object.

Mitigation

This condition is very similar to the case of "Adding enum value used in responses" but instead of strings, it’s about objects. A possible mitigation consists of ensuring that the clients communicate to the backend the discriminated types that are handled by the implementation and offloading the filtering on the business logic (we cannot guarantee that on Swagger spec level). Another option would be to ensure that clients properly handle all the types of discriminated objects, as they have a property in common, but this could easily masquerade errors in the client implementation which could be hard to fix (especially for mobile apps).

---

Removing a discriminated type (model) used as request parameter

Rationale

Polymorphism, done using the discriminator keyword, allows returning different objects that are united by the fact that a string property is required. The content of the property represent the specific type of the object. Removing a discriminated type, that will be used in requests, is backward incompatible as previously valid objects could be sent by clients that are operating with "old" Swagger spec and the backend service will fail to validate the request.

Mitigation

This condition is very similar to the case of "Removing enum value used as request parameter" but instead of string it has objects. Like for the enum case, the general recommended approach is: don't do it and add business logic to ignore such objects.