How to use and document polymorphism in API

Polymorphism is an important concept in API development to help achieve objectives such as easy code changes and scalable API design. It refers to the possibility of using the same endpoint for similar but different objects, reducing the amount of endpoint duplications. In this article, the author explains how polymorphism can be used in API development with examples from a real estate agency application. They also discuss how to properly document polymorphic resources with OpenAPI or AsyncAPI specifications based on JSON Schema. The article covers inheritance and DRY patterns, discriminator support, and provides an example of how to use the oneOf combinator for defining alternatives in API documentation.