Add polymorphism support to generated OpenAPI json and UI

[asvishnyakov]

@asvishnyakov commented on Tue Mar 20 2018

Research point: https://github.com/Azure/autorest/blob/master/docs/developer/guide/defining-clients-swagger.md#polymorphism

---

@asvishnyakov commented on Thu Aug 02 2018

Updated 27 Mar 2019

Status:

• OpenAPI generation:
  • Swashbuckle is actually died and not support polymorphism, Swashbuckle.AspNetCore (actually it's .NET Standard library, so it can be used in current platform) actively maintained and now support ^[1][2] polymorphism in preview (status at 27 Mar 2019).
    • Third-party nuget available for ASP.NET Core version
  • NSwag support polymorphism
• UI:
  • swagger-ui: has no support and has no plans to implement in near future
  • ReDoc: support polymorphism, but have no built-in console
• Code generation:
  • AutoRest: support polymorphism
  • NSwag can also be used for generation

Resolution: the blocking issue is UI support: swagger ui has no support of polymorphism, while ReDoc has no built-in console. For OpenAPI generation we may have a few solutions, code generation already ready for polymorphism and not require any additional actions.

[Woland2k]

don't swagger UI is that critical, unless it crashes

[yecli]

It is working. Storefront is receiving derived objects together with base ones in array using autorest client.
Sample prototype extending Platform API implemented in this commit.

[yecli]

Usage example:
Add info about base polymorphic types to your module manifest (assembly qualified name), so not info on derived types needed:

    <openAPIPolymorphicTypes>
        <assemblyQualifiedTypeName>VirtoCommerce.Domain.Cart.Model.LineItem, VirtoCommerce.Domain</assemblyQualifiedTypeName>
    </openAPIPolymorphicTypes>

Your base and derived types should have property public string Type containing value Type.Name (or Type.FullName in case UseFullTypeNameInSwagger = true for the module).

[asvishnyakov]

@yecli Can we do that in code? I don't think it's good idea to put .NET-specific information into manifest. Also, in code we can use nameof() operator and use Assembly class, while here we can make mistake in type & assembla names

[yecli]

@asvishnyakov First it was implemented in code using custom attribute for polymorphic base type. But there were some problems when we want to make type from dependent assembly as polymorphic base for specific module (e.g. LineItem from Domain for Cart module) - in such cases we would need to load dependent assemblies to search polymorphic types. Moved polymorphic types declaration to module manifests for explicit and clear declaration. Also we already use assembly qualified type names in manifest - for defining module type.

Agree with you, better to do this in the code. @tatarincev said the same and advised to use AbstractTypeFactory for registering polymorphic types. Going to try this solution.

[yecli]

Added special interface to register type to be polymorphic for the module:

    public interface IPolymorphismRegistrar
    {
        IPolymorphicBaseTypeInfo[] GetPolymorphicBaseTypes(string moduleName);
        void RegisterPolymorphicBaseType(string moduleName, IPolymorphicBaseTypeInfo polymorphismBaseTypeInfo);
    }

Example of usage for Customer module polymorphism (Member class and its descendants):

            // Register Member descendants in AbstractTypeFactory
            AbstractTypeFactory<Member>.RegisterType<Organization>().MapToType<OrganizationDataEntity>();
            AbstractTypeFactory<Member>.RegisterType<Contact>().MapToType<ContactDataEntity>();
            AbstractTypeFactory<Member>.RegisterType<Vendor>().MapToType<VendorDataEntity>();
            AbstractTypeFactory<Member>.RegisterType<Employee>().MapToType<EmployeeDataEntity>();

…
            // Use IPolymorphismRegistrar to tell OpenAPI doc generator to use polymorphism for Member and its descendants
            var polymorphismRegistrar = _container.Resolve<IPolymorphismRegistrar>();
            polymorphismRegistrar.RegisterPolymorphicBaseType(ModuleInfo.Id, new PolymorphicBaseTypeInfo<Member>(nameof(Member.MemberType)));

[yecli]

Next mechanism rework: left only AbstractTypeFactory as a source for OpenAPI polymorphism registration.

Usage - when registering type in AbstractTypeFactory, need to fill TypeInfo.Discriminator property with the name of base class discriminator property.
Example for Member type in vc-module-customer:

            // Register Member descendants in AbstractTypeFactory
            AbstractTypeFactory<Member>.RegisterType<Organization>().MapToType<OrganizationDataEntity>().Discriminator = nameof(Member.MemberType);
            AbstractTypeFactory<Member>.RegisterType<Contact>().MapToType<ContactDataEntity>().Discriminator = nameof(Member.MemberType);
            AbstractTypeFactory<Member>.RegisterType<Vendor>().MapToType<VendorDataEntity>().Discriminator = nameof(Member.MemberType);
            AbstractTypeFactory<Member>.RegisterType<Employee>().MapToType<EmployeeDataEntity>().Discriminator = nameof(Member.MemberType); 

Generated OpenAPI doc:
PolymorphicOpenAPI_VirtoCommerce.Customer.zip

[yecli]

Closing as not applicable.