HDOT-1743 Allow to expose polymorphic types in Swagger API

[avas]

Problem

Currently, there is no way to expose derived types in Swagger API description. For example, consider the following code:

// Models definition in ...Core assembly

public abstract class BaseObject
{
    // ...
}

public class DerivedObject : BaseObject
{
    // ...
}

public class AnotherDerivedObject : BaseObject
{
    // ...
}

// Controller method that returns these models
public ActionResult<IList<BaseObject>> GetObjects()
{
    var result = new[] 
    {
        new DerivedObject(),
        new AnotherDerivedObject()
    };

    return Ok(result);
}

In this example, only the BaseObject will be exposed in Swagger. DerivedObject and AnotherDerivedObject will be missing from JSON with API definition, and the only way to expose them is to add some other API method that will explicitly accept or return any of these derived types.

On the other hand, we don't want to enable polymorphism globally, as this might break existing API (e.g. any action from vc-module-customer that works with a Member class).

Solution

Since the creation of VC platform v3, polymorphism support in Swashbuckle improved significantly. Now we actually can use it in actions, and the resulting document will be suitable for AutoRest (e.g. to generate API clients for storefront). An example mentioned above can be reworked like this to expose derived models:

using Swashbuckle.AspNetCore.Annotations;

[SwaggerSubType(typeof(DerivedObject)]
[SwaggerSubType(typeof(AnotherDerivedObject)]
public abstract class BaseObject
{
    // ...
}

public class DerivedObject : BaseObject
{
    // ...
}

public class AnotherDerivedObject : BaseObject
{
    // ...
}

This will expose BaseObject, DerivedObject and AnotherDerivedObject in Swagger API description (despite the fact that GetObjects() method still has only the base type in its signature), and it won't break other API. However, to use this approach, Swashbuckle configuration code needs to be changed a bit.

Proposed of changes

So, I did the following things to achieve this:

1. Installed the Swashbuckle.AspNetCore.Annotations package;
2. Enabled annotation-based control of inheritance and polymorphism. Parameters for the EnableAnnotations() method have the following meaning:
   • enableAnnotationsForPolymorphism allows to use the SwaggerSubType attribute to specify expected derived classes;
   • enableAnnotationsForInheritance retains models inheritance hierarchy. For example, if we generate a Swagger API documentation for the example mentioned above with this parameter set to false, it will not contain the BaseObject type - instead, DerivedObject and AnotherDerivedObject will include its properties. With this parameter set to true, the hierarchy will be preserved.

Additional context (optional)

This approach works and does not break any existing clients generated by AutoRest. However, it has some limitations:

1. If BaseObject has any abstract or virtual properties that are overridden in derived types, Swashbuckle will include these properties both to BaseObject and to derived types. However, AutoRest does not understand that and produces an error like FATAL: System.InvalidOperationException: Found incompatible property types , for property 'someVirtualProperty' in schema inheritance chain. A solution for this would be to avoid using abstract and virtual properties for such types.
2. This approach only works if all of derived types are located in the same module - it won't allow to extend this list from other modules. To overcome this, we might need to make a custom sub-type selector - its code would be based on the existing implementation in Swashbuckle, but use AbstractTypeFactory instead of custom attributes to find descendant types. However, this might require extending the TypeInfo, so that we could explicitly specify what types can be exposed in Swagger API.

Make sure these boxes are checked:

• Check all the changes in github PR - files count (non of them are redundant, have meaningful changes, all are added), if target branch is correct
• Check methods and variable namings - it should be self descriptive, no typos
• Check you did not introduce breaking changes in API and public models/services.
• Respect extensibility - https://community.virtocommerce.com/t/extensibility-basics-the-domain-model-and-persistence-layer-extension/141
• Follow DRY and SOLID principles
• For unit tests - follow Microsoft best practices: https://docs.microsoft.com/en-us/dotnet/core/testing/unit-testing-best-practices
• Consolidate solution dependencies in case you are using newer version, update VC module dependencies in module.manifest. Do not upgrade 3rd party packages that are shipped with the platform with the version newer than in the platform.
• Check code style conventions - https://github.com/VirtoCommerce/styleguide/blob/master/csharp.md
• Check PR have a concise and descriptive title, follow git commit message rules

[mvktsk]

Review task https://virtocommerce.atlassian.net/browse/VP-5447 has been created

[akak1977]

Tested for side effects by comparing cumulative swagger-documents (with/without changes).
They are equal.

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!

0 Bugs
0 Vulnerabilities (and 0 Security Hotspots to review)
0 Code Smells

0.0% Coverage
0.0% Duplication

The version of Java (1.8.0_265) you have used to run this analysis is deprecated and we will stop accepting it from October 2020. Please update to at least Java 11.
Read more here